Install Graph Indexer

Graph Indexer installs with one command: run npx graph-indexer init from your repository root on Node.js 22.5 or newer. It writes project-level MCP configuration for the coding agents it detects, adds a short instruction block to CLAUDE.md or AGENTS.md, keeps .graph-indexer/ out of git, and the index is built the first time the server starts. Graph Indexer is MIT licensed and published on npm.

What are the requirements?

Graph Indexer requires Node.js 22.5 or newer, because it uses the built-in node:sqlite module. Nothing else is needed: no compiler, no native build, no model download, no service to run. The tree-sitter runtime and the 16 language grammars ship as WebAssembly inside the package.

node --version   # v22.5.0 or higher

How do I install Graph Indexer?

From the root of the repository you want to index:

cd your-repo
npx graph-indexer init      # wires the MCP server into the agents it detects
npx graph-indexer index     # optional: build the index now

The index step is optional. The MCP server builds the index on first start and re-syncs it with the files on disk before every answer, so edits made a second ago are visible. After init, restart your agent so it loads the new server, then check the eight tools are listed. If you use Claude Code you can also install through the Claude Code plugin.

What does npx graph-indexer init change?

graph-indexer init writes only project-level files, merges into existing configuration instead of overwriting other servers, and is idempotent. This is what it writes for each agent:

If a JSON file contains comments or is not plain JSON, init leaves it untouched and prints the entry to add by hand.

Besides the MCP entry, init also does the following:

• Adds a managed block to CLAUDE.md (Claude Code) or AGENTS.md (all other agents).
• For Claude Code, writes the code-structure sub-agent to .claude/agents/code-structure.md.
• Appends .graph-indexer/ to .gitignore if it is not already there.

Which flags does init accept?

What does --hooks add?

npx graph-indexer init --hooks adds three Claude Code hooks to .claude/settings.json: PostToolUse (matching Edit|Write|MultiEdit|Grep|Bash|Read), SessionStart and SubagentStart. After an edit, the post-edit check reports syntax errors introduced, calls that no longer fit a changed signature and removed names still in use. Once the agent has been searching and reading for a while without editing, it also says where the names in the lines it read are defined, and which definition is which after a grep for a shared name. Otherwise it stays silent. Devin, Copilot CLI and Cursor also run the Claude Code hooks, and for OpenCode and Kilo Code --hooks writes a plugin to .opencode/plugins/graph-indexer.js or .kilo/plugin/graph-indexer.js.

How do I configure Graph Indexer manually for any MCP client?

Any MCP client can run the Graph Indexer server over stdio. Use this command and arguments, replacing the path with your repository:

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

VS Code uses "servers" instead of "mcpServers" and adds "type": "stdio". For Codex CLI, add this to ~/.codex/config.toml:

[mcp_servers.graph-indexer]
command = "npx"
args = ["-y", "graph-indexer@3", "serve", "--repo", "/path/to/repo"]

Without --repo, the server indexes the git repository that contains its working directory; the GRAPH_INDEXER_REPO environment variable also works. For Claude Desktop, JetBrains AI Assistant and Cline, add an MCP server with command npx and the same arguments.

What is the CLAUDE.md / AGENTS.md block?

Graph Indexer writes a short block, delimited by <!-- graph-indexer:start --> and <!-- graph-indexer:end -->, that tells the agent when to use the index. It is a few lines on purpose: long generated context files measurably hurt agents. The block gives four lookup rules (explore in one pass, read the lines you need rather than whole files, search for definition lines, run the covering tests once) and names the tools for what text search cannot answer exactly: find_references for uses of a shared name, call_graph for callers of callers, change_impact before changing a signature and check_changes afterwards. Running init again updates the block between the markers and leaves the rest of the file alone.

What is the code-structure sub-agent?

For Claude Code, init writes .claude/agents/code-structure.md: a read-only sub-agent that runs on the small haiku model, cannot edit files, and answers call-site, caller, subclass and change-impact questions from the index. The main agent hands these questions off and gets back only a list of path:line entries plus whether the list is complete. A file with that name that you wrote yourself is left as it is, and --no-helper skips it. The Claude Code plugin ships the same sub-agent.

How do I fix common problems?

The server does not start or node:sqlite is missing

Run node --version. Anything below 22.5 lacks the built-in node:sqlite module that Graph Indexer needs. Upgrade Node.js and restart your agent.

The agent does not list the tools

Restart or reload the agent after init. Then check that the config file from the table above contains a graph-indexer entry; if init reported that a file has comments, add the printed entry by hand.

I want to rebuild the index from scratch

Delete the .graph-indexer/ folder in the repository. It holds only the derived index, so removing it is safe, and the next start rebuilds it. The index also rebuilds itself whenever the installed Graph Indexer version changes how it extracts facts. Check its state with npx graph-indexer status.

Where is the index stored, and is it private?

The index lives in <repo>/.graph-indexer/. Graph Indexer itself makes no network calls and sends no telemetry; the agent still sends what it reads to its model provider. See the FAQ and the security policy for details.