# Graph Indexer for Claude Code

> Add Graph Indexer to Claude Code with npx graph-indexer init: it writes .mcp.json, a CLAUDE.md block and a small-model helper sub-agent. Hooks are optional.

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.

```bash
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](/claude-code-plugin/) 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:

| File | Content |
|---|---|
| `.mcp.json` | A `graph-indexer` entry under `mcpServers`, merged with any servers already there |
| `CLAUDE.md` | A short block between `<!-- graph-indexer:start -->` and `<!-- graph-indexer:end -->` with the lookup rules |
| `.claude/agents/code-structure.md` | The structural helper sub-agent, skipped with `--no-helper` |
| `.gitignore` | `.graph-indexer/` so the index stays out of version control |

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:

```json
{
  "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](https://github.com/MaquinaTech/graph-indexer/blob/main/docs/AGENTIC-BENCHMARK.md).

## 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:

| Hook | What it does |
|---|---|
| `PostToolUse` on `Edit`, `Write`, `MultiEdit`, `Grep`, `Bash`, `Read` | After an edit, runs the edit checker on that file; after a grep for a shared name, tells the definitions apart; stays silent otherwise |
| `SessionStart` | Adds one line saying the index exists, and builds it in the background if missing |
| `SubagentStart` | Gives subagents the same line and lookup rules, since they do not read `CLAUDE.md` |

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](/benchmarks/) and the [tools reference](/tools/).

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.

## Frequently asked questions

### Do I need the Claude Code plugin or is init enough?

Either works. init writes project files you can commit and review. The plugin installs through /plugin and bundles the MCP server, the helper and the hooks. Hooks from init are optional.

### Does Graph Indexer add to my Claude Code context?

Yes, a little. The measured footprint is about 1,200 tokens per Claude Code session, because only find_references is loaded up front and the other tools are deferred. Typical tool replies are 400 to 1,500 tokens.

### Will init overwrite my existing .mcp.json?

No. It merges its graph-indexer entry into the existing mcpServers object and leaves your other servers alone. If the file contains comments or is not plain JSON, init leaves it as is and prints the entry to add by hand.

### Does Graph Indexer send my code anywhere?

Graph Indexer itself makes no network calls and sends no telemetry. Claude Code still sends whatever it reads, including tool replies, to its model provider as it normally does.

---

Updated: 2026-10-08 · Graph Indexer 3.0.0 · https://graph-indexer.vercel.app/agents/claude-code/