zerograph

A project knowledge graph that costs zero API tokens to build, keep fresh, and query.

zerograph reads a repository's markdown and code in 24 languages and extracts the structure the authors already wrote: requirement ids, cross-references, exports, imports, calls, decorators, and ids quoted in comments. It answers questions about that structure in a few lines of text.

• Zero tokens by default. Build, refresh and query all run locally. ask --rerank is the only thing that spends model tokens, and only when asked.
• Finds the entry point from plain words. Exact id, BM25 and local dense retrieval find it in about 200 tokens an answer.
• Built for agents. Every reader takes --json, there is an MCP server, and a session hook keeps the graph fresh.

Get started

npm install -g zerograph                   # or: pnpm add -D zerograph
echo .zerograph/ >> .gitignore             # the graph is built per checkout
zerograph build                            # first run downloads the embedding model
zerograph ask cancellation policy          # stays fresh with your edits
zerograph install-agent --claude           # optional: the Claude Code plugin

install-agent also takes --codex (the Codex plugin), --cursor, --copilot, --gemini and --opencode. On Windows, see the Windows notes.

Claude Code plugin

The plugin is how zerograph wires into Claude Code: it starts zerograph's MCP server for the session, briefs each session and subagent on the index, answers a concept grep from the graph before it runs, and names the callers an edit can break. A status mod puts the index's state under the prompt: ◇ zerograph · in sync, a progress bar while a refresh runs, the files behind and whether serve answers. /zerograph prints the full zerograph status report.

/plugin install zerograph --marketplace devmaxxx/zerograph

zerograph install-agent --claude runs the same install through the claude CLI and removes what older releases wrote into the checkout. The plugin is pinned to the latest release, so claude plugin update zerograph moves it with zerograph. It adds /zerograph:ask, /zerograph:impact, /zerograph:trace, /zerograph:changes, /zerograph:explain, /zerograph:status and /zerograph:refresh, each of which calls the server's tools and reads the top hits; see the plugin.

Codex gets the same as a Codex plugin, zerograph install-agent --codex: the MCP server, the session hooks, and the commands as skills ($zerograph:ask, $zerograph:impact, …); see the Codex plugin.

In action

$ zerograph ask cancellation
packages/db/src/schema/salon/scheduling.ts:110  CANCELLATION_CONSEQUENCES
docs/.../BE-M10-payments-provider-stripe-connect-….md:80  BE-M10/T05  Cancellation policy engine (`packages/domain/policy.ts`): inputs policy + appoin…
  └ docs/.../BE-M10-payments-provider-stripe-connect-….md:1  BE-M10  BE-M10 Payments provider: Stripe Connect implementation…

Each line reads path:line [ID] headline. Top-level lines are the matched seeds, and └ lines are neighbours one hop away.

zerograph ask FR-PAY-22                    # an exact id or symbol goes straight to the node
zerograph impact StaffService              # callers by depth, importing files, a risk line
zerograph trace StaffController StaffService   # shortest call chain between two symbols
zerograph changes --base main              # what the diff touches, and who reaches it
zerograph explain FR-PAY-22                # one node and everything attached to it

Worktrees

Each checkout keeps its own graph and index in .zerograph/ (nodes, edges, BM25 and its vectors), so worktrees, clones and branches never share state or see each other's edits. The only thing shared is a cache of embeddings.

• A new worktree builds in seconds. The cache (~/.cache/zerograph/vectors) holds text hash → vector per model and nothing else: no paths, edges or branches. A checkout copies the hits into its own vectors.f32 and embeds only the misses, so a new worktree or clone embeds only the rows no checkout here has embedded before. On zerograph itself, a clone builds in 1.5 s instead of 46 s, with the same answers.
• Parallel agents are safe. One writer lock per checkout means two agents in one worktree never write at once. Agents in different worktrees never wait on each other.
• One resident process per checkout. serve sockets live under ~/.cache/zerograph/sock, keyed by checkout, so a serve in one worktree never answers for another.

The cache is capped by vector_cache_max (default 4G). zerograph cache status shows what it holds and zerograph cache prune trims it. See the vector cache.

Docs

• Use it: install, commands, keeping fresh, serve, MCP, configuration
• Understand it: how it works, the graph model, languages, embeddings, rerank

Contributing

Issues and pull requests are welcome. Before opening a pull request, run cargo test and cargo clippy --all-targets -- -D warnings. A change to retrieval is judged by the three-way rule.

License

MIT.