# Install Graph Indexer

> Install Graph Indexer with npx graph-indexer init: it needs Node.js 22.5+, wires the MCP server into your AI coding agents and builds a local code index.

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](https://www.npmjs.com/package/graph-indexer).

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

```bash
node --version   # v22.5.0 or higher
```

## How do I install Graph Indexer?

From the root of the repository you want to index:

```bash
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](/tools/) are listed. If you use Claude Code you can also install through the [Claude Code plugin](/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:

| Agent | File written | Top-level key |
|---|---|---|
| [Claude Code](/agents/claude-code/) | `.mcp.json` | `mcpServers` |
| [Cursor](/agents/cursor/) | `.cursor/mcp.json` | `mcpServers` |
| [VS Code (Copilot)](/agents/vscode-copilot/) | `.vscode/mcp.json` | `servers` |
| [Gemini CLI](/agents/gemini-cli/) | `.gemini/settings.json` | `mcpServers` |
| [OpenCode and Kilo Code](/agents/opencode/) | `opencode.json` (or an existing `kilo.json`, `.kilo/kilo.json`) | `mcp` |
| [Junie](/agents/junie/) | `.junie/mcp/mcp.json` | `mcpServers` |
| [Zed](/agents/zed/) | `.zed/settings.json` | `context_servers` |
| [Codex CLI](/agents/codex/) | nothing written; prints the TOML for `~/.codex/config.toml` | `mcp_servers` |
| [Devin](/agents/devin/) | nothing written; prints the server entry for Devin's MCP settings | n/a |

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?

| Flag | Effect |
|---|---|
| `--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin` | Configure only the listed agents |
| `--all` | Configure every supported agent |
| `--hooks` | Add the Claude Code hooks to `.claude/settings.json` and the OpenCode / Kilo Code plugin |
| `--local` | Use this checkout of Graph Indexer instead of `npx` |
| `--dry-run` | Print what would change without writing anything |
| `--no-instructions` | Skip the `CLAUDE.md` / `AGENTS.md` block |
| `--no-helper` | Skip the Claude Code `code-structure` sub-agent |
| `--repo DIR` | Target a repository other than the current one |

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

```json
{
  "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`:

```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](/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](/faq/) and the [security policy](https://github.com/MaquinaTech/graph-indexer/blob/main/SECURITY.md) for details.

## Frequently asked questions

### Does Graph Indexer need a build step or a database server?

No. Graph Indexer has zero dependencies, no native builds and no model downloads. Its tree-sitter runtime and grammars ship as WebAssembly inside the npm package, and the index is a local SQLite file in .graph-indexer/.

### Can I install Graph Indexer for only one agent?

Yes. Pass --agents with a comma-separated list, for example npx graph-indexer init --agents claude,cursor. Without flags, init configures the agents it detects in the repository, and falls back to Claude Code.

### Is it safe to commit the .graph-indexer folder?

No. The index contains excerpts of your code, so treat it like the repository itself. init adds .graph-indexer/ to .gitignore, and deleting the folder is safe: it is rebuilt on the next start.

---

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