Graph Indexer for Claude Code

Graph Indexer for Claude Code is a local MCP server plus a read-only helper sub-agent that gives Claude Code exact references, call graphs and change impact from a tree-sitter index of your repository. Run npx graph-indexer init in the project root; it writes .mcp.json, a managed block in CLAUDE.md and .claude/agents/code-structure.md.

How do I add Graph Indexer to Claude Code?

Run this from the repository root. Node.js 22.5 or later is required.

npx graph-indexer init
npx graph-indexer index   # optional: build the index now

Claude Code is the fallback: if init finds no agent folders in the repository, it configures Claude Code. To target it explicitly, use npx graph-indexer init --agents claude.

Prefer the plugin route? Inside Claude Code run /plugin marketplace add MaquinaTech/graph-indexer and then /plugin install graph-indexer@graph-indexer. The Claude Code plugin page explains what the plugin bundles and when to choose it over init.

What does npx graph-indexer init write for Claude Code?

For Claude Code, init makes these changes, all idempotent:

An existing .claude/agents/code-structure.md that you wrote yourself is left untouched.

What does the manual configuration look like?

The entry init adds to .mcp.json is a plain stdio server:

{
  "mcpServers": {
    "graph-indexer": {
      "command": "npx",
      "args": ["-y", "graph-indexer@3", "serve"]
    }
  }
}

Without --repo, the server indexes the git repository containing its working directory. Claude Code starts it in the project, so no path is needed.

What is the code-structure helper?

The Claude Code helper code-structure is a read-only sub-agent that runs on the haiku model and has Edit, Write, MultiEdit and NotebookEdit disallowed. The main agent hands it structural questions: every call site of a method, callers of callers, classes that implement an interface, what a change would affect. It answers from find_references, call_graph and change_impact and returns only a path:line list, so the lookup stays out of the main context.

In the project’s benchmark, 24 questions delegated this way were answered 20 of 24 exactly, the same as a general-purpose sub-agent using grep, at 76% lower cost and 72% less time. Details are in the agentic benchmark.

Which hooks does Graph Indexer add to Claude Code?

npx graph-indexer init --hooks merges three hooks into .claude/settings.json without removing your own:

Hooks fail open: any error, timeout or irrelevant input prints nothing. The plugin ships the same three hooks.

What does Claude Code gain?

Claude Code gains eight read-only tools. find_references is marked always-loaded, so it stays visible even when Claude Code defers MCP tools behind tool search. Here is what each one answers:

• find_references lists every use of a symbol bound to the definition it points at, and says whether the list is complete.
• call_graph traces callers and callees across files.
• change_impact gives the blast radius of a change and the tests to run.
• check_changes verifies uncommitted edits without a build.
• read_code, search_text, search_code and outline read and locate code with line numbers.

On 400 nestjs symbols checked against the TypeScript compiler, find_references returned 99.7% real references with 96.2% recall; grep reached 12.8% precision. See the benchmarks and the tools reference.

The honest limit: fixing real issues showed no measurable saving in the benchmark, because on real issues the agent often did not call the index.