code-intel

Code Intelligence

Three tools, three zoom levels. They are complementary, not competing — pick the layer that matches the question.

Layer	Tool	Answers	Mechanism
Comprehend	graphify	"What is this project, how do the big pieces (incl. docs/schema) connect?"	Multimodal knowledge graph, snapshot
Locate	vera	"Where's the code about X?" when you don't know the symbol name	Embedding semantic search
Traverse	codegraph	"Who calls this? What does it call? Blast radius of a change?"	Structural call graph, live over MCP
Resolve	LSP / ast-grep	"What exactly is this symbol, and what are its real references?"	Compiler truth; AST patterns. No index

The first three need a built index and go stale between refreshes. The fourth needs nothing and is always available — reach for it freely, including in small repos where indexing isn't worth it.

When to reach for this

The disqualifier is size, not familiarity: if the repo is small enough to just read the relevant files, skip the indexes — LSP + grep are faster. Otherwise it pays off, and a repo you know cold still qualifies, because I start every session cold even when you don't.

Index when a repo is large, polyglot, long-lived, or already has a .codegraph/ or .vera/ index. Skip a 20-file utility.

Default to the index when one exists — don't wait to be asked. If the repo has a .codegraph/, reach for codegraph's MCP tools over grep/Read for navigation; if it has a .vera/, prefer vera search over broad text search.

Two modes

• Exploring an unfamiliar repo — work the layers in order: graphify to comprehend, vera to locate, codegraph to traverse.
• Daily work in a repo you own — codegraph and vera both run ambiently (see Staying fresh without asking), so lead with codegraph for navigation and impact checks. Reach for vera when you cross into code you didn't write, and graphify only for architecture questions or a refactor. This is the default when the index is present — no special prompt needed.

Routing

You need to…	Use	How
Orient in an unfamiliar repo; map architecture and how code + docs + schema connect	graphify	/graphify . (in-agent) then read graphify-out/GRAPH_REPORT.md, or graphify query "<question>"
Find where behavior lives without knowing the name	vera	vera search "validates JWT expiry"
Exact string, regex, import, or TODO	vera (or rg)	vera grep "pattern"
Trace who calls a symbol / what it calls	codegraph	MCP codegraph_callers / codegraph_callees (CLI: codegraph callers <sym>)
Assess the blast radius before changing a symbol	codegraph	MCP codegraph_impact (CLI: codegraph impact <sym>)
Enumerate the exact references to a symbol (before a rename or signature change)	LSP	lsp_references in pi; grep both over- and under-reports — it hits comments and misses aliased imports
Rename a symbol safely	LSP	lsp_rename — only the language server knows which occurrences are the same symbol
Match a code shape rather than a literal string	ast-grep	ast-grep run -p '$A.then($B)' — immune to formatting and line breaks
Mechanical multi-file refactor	ast-grep	ast-grep run -p <pat> -r <rewrite>; check codegraph impact first
Build task context (entry points + related symbols, few calls)	codegraph	MCP codegraph_context "<task>"

When codegraph's MCP tools are available, prefer them over re-deriving structure with grep — answer directly rather than delegating to file-reading sub-agents (that erases the savings).

Per-tool detail

• vera — see the vera skill for full search / grep / references / overview flags. Index with vera index .; a watcher normally keeps it current, so vera update . is only for a repo you are not watching.
• codegraph — MCP tools: codegraph_context, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_node, codegraph_files, codegraph_status. Same verbs exist as CLI subcommands. Index with codegraph init + codegraph index; the file watcher auto-syncs while serve --mcp runs. 19+ languages (no shell/zsh).
• graphify — the full graph is built in-agent with /graphify . (the session supplies the LLM for semantic extraction); the CLI's graphify update . does a code-only AST graph with no LLM. Both write graphify-out/ (graph.json, GRAPH_REPORT.md; HTML viz only under ~5k nodes). Query with graphify query "…", graphify path "A" "B", graphify explain "Symbol".

Overlap — which wins

• Structural references: codegraph beats vera references (true call edges vs. embedding-derived). Use codegraph to traverse.
• Semantic search: vera is the only one that finds code by meaning. That's its unique slice.
• Non-code: graphify is the only one that maps docs, schemas, and infra alongside code.
• References for a refactor: LSP beats codegraph — it's compiler-exact within a project and never stale. codegraph wins on breadth (whole repo, cross-language, no per-language server needed).
• Renames: LSP always. ast-grep -r and sed only know what looks alike, which is how a rename quietly corrupts a comment or an unrelated same-named field.

Setup per project

Indexes are built on demand, not at install. The code-intel helper drives all three at once:

code-intel init       # build all three indexes (+ graphify commit hook)
code-intel refresh    # update them after edits
code-intel status     # show index state per tool
code-intel watch      # keep vera fresh as files change (see below)

Staying fresh without asking

refresh is for the case where nothing is watching. Normally nothing needs to run, because each tool has its own cadence:

Tool	Kept fresh by	Cadence
codegraph	its own file watcher, inside serve --mcp	live, whole session
vera	one detached vera watch per worktree	live, 2s debounce
graphify	the graphify hook install commit hook	per commit

Only vera needed wiring. A Claude Code SessionStart hook, plus a PostToolUse hook on file edits, runs code-intel watch --ensure, which starts a watcher unless one is already alive — the hot path is a single kill -0. The watcher outlives the session on purpose: interrupting a running vera update corrupts its content-hash bookkeeping, so it exits itself after CODE_INTEL_WATCH_IDLE_MIN minutes (default 120) of no index activity instead of being killed at session end. code-intel watch --status lists every running watcher and --stop (or --stop --all) ends them.

graphify stays on commits deliberately: its full graph needs in-agent LLM extraction, so a per-keystroke rebuild would be slow and would drop the semantic layer.

Or per tool: vera index . / vera update . (or vera watch . for live freshness); codegraph init + codegraph index / codegraph sync (auto-syncs while its MCP server runs); /graphify . in-agent for the full graph or graphify update . for a code-only CLI build (graphify hook install rebuilds on each commit).

.vera/, .codegraph/, and graphify-out/ are gitignored globally. Install/upgrade the tools with the code-intel topic (code-intel/install.sh).

No project index is needed for the resolve layer. ast-grep comes from the Brewfile/pacman list. The shared language-server baseline (typescript-language-server, TypeScript, gopls, and pyright) is managed by mise; Rust uses rustup's rust-analyzer component, while Pi also reuses Neovim Mason servers.

In pi

pi has no MCP, so these are exposed as native tools by the code-intel and lsp extensions instead (pi/config/extensions/, documented in pi/README.md): cg_*, vera_search, ast_search/ast_rewrite, and lsp_*. /code-intel strict there removes text search entirely, which is the honest way to test whether this layer actually helps.