# Graph Indexer for OpenCode

> Add Graph Indexer to OpenCode with npx graph-indexer init: it writes opencode.json and an optional plugin so OpenCode gets exact references locally.

Graph Indexer for OpenCode is a local MCP server that gives OpenCode exact references, call graphs and change impact from an index of your repository. Run `npx graph-indexer init` and it adds a `graph-indexer` entry to `opencode.json`; with `--hooks` it also installs an OpenCode plugin.

## How do I add Graph Indexer to OpenCode?

From the repository root, with Node.js 22.5 or later:

```bash
npx graph-indexer init
```

`init` configures OpenCode when it finds `opencode.json`, `opencode.jsonc` or a `.opencode` folder. To force it, use `npx graph-indexer init --agents opencode`. OpenCode and [Kilo Code](/agents/kilo-code/) share one `init` target, because Kilo Code reads the same configuration.

## What does `npx graph-indexer init` change for OpenCode?

For OpenCode, `init` touches these files:

| File | Content |
|---|---|
| `opencode.json` | A `graph-indexer` entry under `mcp`, merged with your other servers |
| `AGENTS.md` | A managed block with the lookup rules and when to call each tool |
| `.gitignore` | `.graph-indexer/`, where the local index lives |
| `.opencode/plugins/graph-indexer.js` | The plugin, only with `--hooks` |

Use `--dry-run` to preview everything and `--no-instructions` to skip the `AGENTS.md` block. Re-running `init` updates the block in place between its `graph-indexer:start` and `graph-indexer:end` markers.

## What does the manual OpenCode configuration look like?

OpenCode uses its own MCP format: a `mcp` object, a `local` type and the command as a single array. The entry `init` writes is:

```json
{
  "mcp": {
    "graph-indexer": {
      "type": "local",
      "command": ["npx", "-y", "graph-indexer@3", "serve"],
      "enabled": true
    }
  }
}
```

With `init --local`, the command points at the `bin/graph-indexer.mjs` of your checkout instead of `npx`.

## What does the OpenCode plugin do?

The Graph Indexer plugin for OpenCode appends short, factual context to the output of OpenCode's `read`, `grep`, `bash`, `edit` and `write` tools. It asks the repository's resident Graph Indexer process over a local socket, never over the network. It adds three things:

- Once the agent is crawling (several searches or reads since the last edit), a read also shows where the names in those lines are defined.
- After a search that missed a definition, the output says where the definition is.
- After an edit, it reports what the edit broke: syntax errors, calls that no longer fit a changed signature, removed names still in use.

The plugin fails open: if the process does not answer, it adds nothing. Install it with `npx graph-indexer init --hooks`. See [how it works](/how-it-works/) for the resident process.

## What does OpenCode gain from Graph Indexer?

OpenCode's agent gets eight read-only tools. `find_references` lists every real use of a symbol, bound through scopes, imports and receiver types. `call_graph` shows callers and callees, `change_impact` shows dependents and the tests to run, and `check_changes` verifies uncommitted edits without a build.

Against the TypeScript compiler on 400 nestjs symbols, `find_references` reached 99.7% precision and 96.2% recall, where grep reached 12.8% precision ([benchmarks](/benchmarks/)). Graph Indexer is not a type checker: generics, reflection, `any` and dependency-injection tokens are only partly visible. Graph Indexer itself makes no network calls and sends no telemetry; OpenCode still sends what it reads to its model provider. See the [tools reference](/tools/) and the [other agents](/agents/).

## Frequently asked questions

### Does Graph Indexer need the OpenCode plugin to work?

No. The MCP server alone gives OpenCode all eight tools. The plugin is optional and only adds context to the output of OpenCode's own read, grep, bash, edit and write tools. It is written only when you pass --hooks.

### What happens if the plugin cannot reach Graph Indexer?

It adds nothing and leaves the tool output untouched. On the first miss it starts the Graph Indexer background process for the next calls. Any error is swallowed, so a plugin problem never breaks an OpenCode tool call.

### Why does the OpenCode entry have no --repo argument?

OpenCode starts the server inside the project, and without --repo Graph Indexer indexes the git repository of the current directory. You can still pass --repo or set GRAPH_INDEXER_REPO to point it at another path.

### What if my opencode.json has comments?

init never rewrites a config whose comments or JSONC syntax a JSON round trip would lose. It leaves the file as is and prints the exact entry to paste under mcp, so nothing in your configuration is lost.

---

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