graphpilot-oss/graphpilot

Structural memory for coding agents.
A refactor-safe, branch-aware, evidence-backed code graph that runs entirely on your machine.
Quickstart ·
Tools ·
How it works ·
Editor setup ·
Limitations ·
Benchmarks
---
What it is
GraphPilot is a local CLI + MCP server that indexes your TypeScript/JavaScript repo into a structural graph (symbols, callers, callees, blast radius) and exposes it to coding agents — Claude Code, Cursor, Cline, Windsurf, Continue — so they stop re-grepping the same files every conversation.
The problem it solves: agents burn tokens, hallucinate function names, and miss structural relationships ("what calls this?", "what breaks if I rename it?") because each session starts from zero. GraphPilot is the persistent structural memory in between.
**Token cost drops. Hallucinations drop. Refactors get safer.**
Put a real coding agent (claude-sonnet-4-5) on **40 structural questions about fastify** — a ~300-file Node.js framework — and give it nothing but file reads. Then hand it GraphPilot's four tools and ask the same 40. The agent with GraphPilot uses **61 % fewer tokens**, costs **$3.68 instead of $8.88 — $5.20 saved per session** — and gets **more** of them right, not fewer (37 correct vs 33). Same model, same questions, same repo; the only change is whether the structural index is there. Reproduce it →
A separate correctness benchmark backs the savings with precision: on 10 standardized structural queries GraphPilot scores **F1 0.89 vs grep's 0.42** while reading **99.9 % fewer bytes** (721 B vs 528 KB), and the byte-cost win holds at scale — indexing **microsoft/TypeScript** (601 files, 17 k symbols, 70 k call edges in 10 s) gives **sub-millisecond queries** and a **99.99 % bytes-read reduction**. Full methodology →
One binary, two modes
GraphPilot ships as a single npm package (@graphpilot-oss/graphpilot) with two runtime modes — most users run both.
| Mode | Command | What it does |
| -------------- | -------------------------- | ---------------------------------------------------------------------------- |
| **CLI** | graphpilot index | Walks your repo, builds the structural graph, writes it to ~/.graphpilot/ |
| | graphpilot watch | Keeps the graph fresh (~10 ms per file save) |
| | graphpilot status | Health probe — when the graph was last refreshed, file/symbol/edge counts |
| **MCP server** | graphpilot mcp | Speaks MCP over stdio — your coding agent calls into this to query the graph |
**The flow:** the **CLI** builds the index once (and watch keeps it warm). The **MCP server** is what your coding agent talks to — you never invoke it yourself, you just point your agent's MCP config at graphpilot mcp once and the agent spawns it on every session.
/graph.json; the read-only graphpilot mcp server reads it and serves your coding agent over stdio JSON-RPC" width="720" />
If you only want CLI access to your code graph (no agent), run graphpilot index and then graphpilot stats / inspect graph.json directly. If you only want the agent integration, you still need to run graphpilot index once — the MCP server is read-only against the on-disk graph.
What makes it different
Other code-graph tools treat your repo as a static blob: index once, query forever, no branch awareness, no proof of where an answer came from. GraphPilot is built around three properties none of them ship:
- 🔍 **Evidence anchors.** Every tool response carries file:line @ sha on every symbol and call site. The agent can quote the anchor verbatim and you can verify it instantly — hallucinations get exposed the moment you jump to the line.
- 🌿 **Differential impact.** Pass since: to gp_impact and the result is filtered to files your branch actually touches. PR-scoped refactor analysis in one call instead of git diff | xargs grep.
- 🪵 **Worktree-aware by default.** Two git worktree add-ed branches naturally produce two separate indexes — no manual config. Run graphpilot index ./src/feature from a subdir and it transparently re-roots to the worktree top. Opt out with --no-worktree.