GraphPilot

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.

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.

Add to that: local-first (no telemetry, no remote calls, enforced by an ESLint policy on src/ itself), deterministic (same repo → same graph), sub-second incremental updates via watch mode.

Quickstart

Prerequisites

• Node.js ≥ 20 (node --version to check)
• An MCP-capable coding agent (Claude Code, Cursor, Cline, Windsurf, or Continue)
• A TypeScript or JavaScript repo to index

End-to-end time: ~3 minutes.

1. Install the CLI

npm install -g @graphpilot-oss/graphpilot

or: pnpm add -g @graphpilot-oss/graphpilot

or one-shot, no install: npx @graphpilot-oss/graphpilot

Verify it landed on your PATH:

graphpilot --version

→ 0.1.0

If you see command not found: graphpilot, your global npm bin is not on PATH. Run npm config get prefix and add /bin to your shell's PATH, or use the npx form above.

2. Build the structural index for your repo

Run this once per project. It walks your source tree, parses each TS/JS file with tree-sitter, extracts symbols + call edges, and writes the graph to ~/.graphpilot/ /graph.json.

graphpilot index ~/code/my-app

Expect a one-line summary like indexed 412 files · 3,981 symbols · 7,204 edges · 1.8s.

3. Wire it into your coding agent

GraphPilot speaks MCP over stdio. Add this server entry to your agent's MCP config — every supported client uses the same two-line shape:

{

"mcpServers": { "graphpilot": { "command": "graphpilot", "args": ["mcp"] } } }

Where this file lives depends on the client (~/.cursor/mcp.json, ~/.claude.json, Cline's settings panel, etc.). Pre-made configs with the exact file path for each agent are in examples/ — copy the one for your client.

Restart the agent. It now has four new tools: gp_recall, gp_callers, gp_impact, gp_index — see The four tools below for what each one does and when the agent should reach for it.

4. Try it

Ask your agent a structural question instead of letting it grep:

_"Use gp_impact to show me everything that breaks if I rename parseToken."_

You should see a response with file:line @ sha anchors you can click straight to. If the agent doesn't reach for the tool, prompt explicitly: "use the gp_ MCP tools." If it can't see them at all, the MCP config wasn't picked up — run graphpilot doctor to pinpoint why (or see docs/troubleshooting.md), then restart the agent.

5. Keep the index fresh as you edit (optional but recommended)

graphpilot watch ~/code/my-app

Sub-10 ms incremental updates on each file save. Leave it running in a terminal tab.

6. Drop per-editor routing rules into your repo (optional)

graphpilot init

Auto-detects which editors you have installed (Cursor, Claude Code, Cline, Windsurf, Continue) and writes the matching rules file (.cursorrules, CLAUDE.md, etc.) to the current directory. The rules teach the agent to reach for gp_* tools before grep.

graphpilot init --all            # write rules for every supported editor

graphpilot init --client cursor # one editor only graphpilot init --dry-run # preview without writing

Full 5-minute walkthrough with screenshots: docs/quickstart.md.

The four tools

GraphPilot exposes four MCP tools. Each one answers a structural question your agent would otherwise solve by grepping and reading files.

gp_recall — find a symbol by name

Use this when the agent asks "where is X defined?" or needs to locate a function before reasoning about it.

• Input: { query, limit?, substring?, path? }
• Returns: symbols matching the name (exact case-insensitive by default; substring: true for partial matches), each with file:line @ sha.
• Replaces: grep -rn "function X" plus reading each hit to find the real definition.

Agent: gp_recall({ query: "parseToken" })

→ parseToken (function) — src/auth.ts:42 @ a1b2c3d export function parseToken(raw: string): Token | null

gp_callers — list callers (or callees)

Use this when the agent needs to know "who calls X?" or "what does X call?" — the two fundamental questions of refactoring.

• Input: { symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }
• Returns: every call edge where the symbol is target (callers) or source (callees), with anchors.
• Replaces: grep -rn "X(" followed by manual filtering of comments, strings, and renamed shadows.

Agent: gp_callers({ symbol: "authenticate", direction: "callers" })

→ login → authenticate — src/routes/login.ts:18 @ a1b2c3d → refreshSession → authenticate — src/session.ts:64 @ a1b2c3d

gp_impact — blast radius in one call

Use this when the agent asks "what breaks if I rename X?" or "what depends on this?" — the single most expensive question an agent normally solves.

• Input: { symbol, depth? (1–5, default 3), since?, path? }
• Returns: direct callers, transitive callers grouped by BFS depth, tests likely affected, public-API flag, summary stats.
• Killer feature: pass since: 'main' and the result is scoped to files your branch actually touches — PR-scoped refactor review without git diff gymnastics.

Agent: gp_impact({ symbol: "extractSymbols", depth: 2, since: "main" })

→ Direct callers (2): indexDirectory, applyUpdate → Depth-2 callers (1): cmdIndex → Tests affected (3): tests/indexer.test.ts, tests/symbols.test.ts, tests/cli.test.ts → Public API: no

gp_index — refresh from inside the agent

Use this after the agent (or the user) has made a batch of structural edits and wants the graph to reflect them without dropping to a shell.

• Input: { path? }
• Returns: re-indexes the repo and invalidates the per-path query cache.
• Pairs with: graphpilot watch for sub-10 ms incremental updates between explicit re-indexes.

How it works

<img src="docs/diagrams/how-it-works.svg" alt="How GraphPilot works, in two phases. Build time (CLI index/watch): your repo flows through indexer.ts, parser.