Cage Match: CodeSight vs. OptiVault

Abstract Syntax Tree solutions to token burn.

I don’t even remember where I initially heard of CodeSight, but it was one of those tools one “must install ASAP” because it’s just obviously right. I couldn’t sleep on Sunday, so I got out of bed around 0500, and blundered into this post about OptiVault before I was even half awake.

What you see here is Cowork’s comparison between two conceptually similar tools - they use Abstract Syntax Tree to explore the logical structure of source code. This is just slop, but it’s slop in response to a computer scientist’s eye on the vexing problem of the moment, so maybe it’s worth a look if you’re trying to pick some tooling, but you don’t have the same education/experience I bring to the task.

-=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=-

Prompt: Here are repos for two different Abstract Syntax Tree based tools meant for use with Claude Code. Compare them and give me a broad ranging report on the differences, but try to keep it terse. Don't explain basic computer science concepts, focus on the advances.

Codesight vs. OptiVault: Comparative Analysis

Both are zero-dependency TypeScript CLI tools that compress codebases into compact representations for AI assistants, both offer MCP server modes, and both claim ~90-95% token reduction. The interesting differences are in what they optimize for.

Extraction Philosophy

Codesight is a semantic extractor — it understands what your code does. It identifies routes, ORM schemas, React components, middleware types, env vars, and library exports as first-class structured concepts. Its 8 parallel detectors each target a specific architectural concern and produce typed data (e.g., RouteInfo with method, path, params, tags like [auth, db, payment]). The output reads like an architecture document.

OptiVault is a structural compiler — it understands how your code is organized. It produces per-file “skeletons” containing dependency wikilinks and export signatures, plus a master RepoMap. It doesn’t know what a route or a schema model is; it knows that auth.ts exports verifyToken(token: string): Promise<boolean> and depends on database and crypto. The output reads like an index.

AST Strategy

Codesight dynamically loads the TypeScript compiler from the scanned project’s node_modules (three-level fallback: createRequire → direct path → pnpm store). This gives it real AST access for framework-specific deep extraction — walking NestJS decorator trees, resolving tRPC nested routers, chaining Drizzle field modifiers (.primaryKey().notNull() → pk, required flags). For Python and Go, it spawns lightweight subprocesses or uses structured regex with brace-depth tracking. Every result carries a confidence: "ast" | "regex" tag.

OptiVault never loads a compiler. Its entire AST layer is regex-based with brace-depth tracking for function body extraction. This is simpler and faster (no dependency on the scanned project having TypeScript installed), but it can only extract syntactic features — imports, exports, function signatures — not semantic features like route prefixes accumulated through middleware chains.

Scope of Understanding

That last row is significant. OptiVault’s read_function_code tool lets Claude request just one function’s source without reading the whole file — a capability Codesight doesn’t offer. And mtime caching means OptiVault’s watch mode patches individual RepoMap entries in ~20ms.

Output Model

Codesight generates a .codesight/ directory with domain-specific markdown files (routes.md, schema.md, components.md, etc.) plus a combined CODESIGHT.md. It also generates AI config files for multiple tools (CLAUDE.md, .cursorrules, copilot-instructions.md, AGENTS.md, codex.md). Its MCP server exposes 8 filtered query tools (e.g., get_routes filtered by prefix/tag/method).

OptiVault generates an _optivault/ directory as an Obsidian-compatible vault — each source file gets a corresponding .md note with TOON frontmatter (tgt, dep, exp fields) and a Signatures section. The master _RepoMap.md is a single-file index. Its MCP server exposes 4 tools, the most distinctive being sync_file_context which Claude is required to call after every file write (enforced via auto-generated CLAUDE.md).

Self-Enforcing Protocol

OptiVault’s most novel idea is the closed-loop protocol: it auto-generates a CLAUDE.md directive that forces Claude to (1) always consult the RepoMap before exploring, (2) read skeletons before full files, and (3) call sync_file_context after every write. This keeps the vault in sync as Claude edits code. Codesight has no equivalent write-back mechanism — it’s read-only context generation.

Language & Framework Coverage

Codesight is dramatically wider. It handles 25+ web frameworks for route detection, 8 ORMs for schema parsing, and 10 languages. OptiVault supports TypeScript/JavaScript and Python with a plugin interface for extension. OptiVault’s plugin system (LanguagePlugin) is cleaner for adding new languages, but Codesight ships with far more built-in coverage.

Testing

Codesight uses Node’s built-in test runner (27 tests, fixture-based with synthetic projects written to temp dirs). OptiVault uses Vitest (99 tests, heavily mocked with vi.mock()). OptiVault’s test coverage is substantially more granular.

Summary

Codesight answers: “What does this codebase do?” — routes, schemas, components, middleware, blast radius. Best for onboarding an AI to an unfamiliar project where architectural understanding matters.

OptiVault answers: “How is this codebase wired together, and what can I call?” — dependency graph, export signatures, function bodies on demand. Best for ongoing AI-assisted development where the vault stays in sync with edits and Claude navigates surgically rather than reading whole files.

They’re complementary more than competing. Codesight gives you the map; OptiVault gives you the GPS turn-by-turn.

-=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=--=@=-

Prompt: Are they safe to employ against the same repositories?

Short answer: yes, they’re safe to run together. There are no destructive conflicts.

Output directories don’t overlap — .codesight/ vs _optivault/. They’ll never touch each other’s artifacts.

CLAUDE.md is the only shared file, and both tools are append-only with independent idempotency guards. Codesight checks for the substring "codesight", OptiVault checks for an HTML comment sentinel <!-- optivault-protocol -->. Neither marker triggers the other’s guard, so both sections coexist cleanly. After one run each, both stabilize — re-runs are no-ops.

.gitignore is only modified by OptiVault (to exclude its vault dir). Codesight doesn’t touch it.

Runtime is also safe. Codesight’s AST layer loads the TypeScript compiler from the scanned project’s node_modules; OptiVault never loads a compiler at all. No shared state, no lock contention.

One thing to be aware of: if you run both as MCP servers simultaneously, Claude will see 12 tools (8 from Codesight + 4 from OptiVault). The generated CLAUDE.md will contain two protocol directives — Codesight’s architectural context plus OptiVault’s “always consult the RepoMap first / call sync_file_context after writes” protocol. These aren’t contradictory, but they do create competing attention demands on Claude’s context window. Whether Claude actually follows both protocols faithfully under that load is a prompt-engineering question more than a safety question.