GraphPilot is a local CLI plus MCP server that provides structural memory for coding agents. It indexes your TypeScript/JavaScript repository once into a structured graph (symbols, callers, callees, impact radius), and exposes it to coding agents (Claude Code, Cursor, Cline, Windsurf, Continue) via MCP, avoiding re-grepping the same files in every conversation.
The problem it solves: agents consume tokens, hallucinate function names, and miss structural relationships ("who calls this?" "what will renaming break?") because every session starts from scratch. GraphPilot acts as persistent structural memory. According to the official description, token costs drop, hallucinations decrease, and refactoring becomes safer.
Benchmark data (from official materials): on fastify (a Node.js framework of about 300 files), using a real coding agent (claude-sonnet-4-5) to answer 40 structural questions, comparing file reads alone versus giving GraphPilot four tools. The agent using GraphPilot reduced token usage by 61%, cost $3.68 instead of $8.88, saving $5.20 per session, and answered more correctly (37 versus 33). Another correctness benchmark: on 10 standardized structural queries, GraphPilot F1 0.89, grep 0.42, with bytes read reduced by 99.9% (721 B versus 528 KB). Indexing microsoft/TypeScript (601 files, 17k symbols, 70k call edges) took 10 seconds, queries are sub-millisecond, and bytes read are reduced by 99.99%.
Run modes: a single npm package @graphpilot-oss/graphpilot, with two runtime modes. The CLI builds the index (watch keeps it hot-updated). The MCP server is called by coding agents—you point the agent's MCP configuration at graphpilot mcp once, and the agent starts it itself each session. If you only need CLI access, run graphpilot index and then view it via graphpilot stats / inspect graph.json. If you only need agent integration, you still need to run graphpilot in once firstdex, the MCP server is read-only for graphs on disk.
Differentiating features: Evidence anchors—every symbol and call site in every tool response carries file:line @ sha, so agents can cite verbatim and you can verify immediately. Diff impact—pass since: <commit|branch> to gp_impact, and results are filtered to files the branch actually touched, completing PR-scope refactoring analysis in one call. Worktree awareness—two branches added by two git worktree adds naturally produce two independent indexes, with no manual configuration; running graphpilot index ./src/feature from a subdirectory automatically relocates to the worktree top level, and can be disabled with --no-worktree. In addition: local-first (no telemetry, no remote calls, enforced by ESLint policy), deterministic (same repo, same graph), sub-second incremental updates in watch mode.
Requirements: Node.js ≥ 20, an MCP-capable coding agent (Claude Code, Cursor, Cline, Windsurf, or Continue), and a TypeScript or JavaScript repository to index. End-to-end takes about 3 minutes.
Quick start: 1. Install the CLI (global npm package). 2. Build the structural index for the repository (run once per project; parses TS/JS files, extracts symbols and call edges, writes to ~/.graphpilot/<repo-id>/graph.json). 3. Connect the coding agent: GraphPilot speaks MCP over stdio; add the server entry to the agent's MCP configuration; all clients use the same two-line structure; preset configurations are in examples/. After restarting the agent, four tools become available: gp_recall, gp_callers, gp_impact, gp_index. 4. Ask the agent structural questions, for example "use gp_impact to show what breaking a rename of parseToken would break"; you should see responses with file:line @ sha anchors. If the agent does not call the tools, explicitly prompt "use the gp_ MCP tools"; if you cannot see the tools, run graphpilot doctor to diagnose and then restart the agent. 5. Optional: run graphpilot watch to keep the index fresh, with sub-10 ms incremental updates on every file save. 6. Optional: run the command to write per-editor routing rules into the repository, automatically detecting installed editors and writing matching rule files (such as .cursorrules, CLAUDE.md, etc.), teaching the agent to use gp_* tools before grep.
Four MCP tools: gp_recall—find symbols by name, input { query, limit?, substring?, path? }, returns matching symbols with file:line @ sha, replacing grep -rn "function X" plus rereading. gp_callers—list callers or callees, input { symbol, direction?: 'callers' | 'callees', limit?, includeUnresolved?, path? }, returns each call edge with anchors. gp_impact—get the impact scope in one call, input { symbol, depth? (1–5, default 3), since?, path? }, returns direct callers, transitive callers grouped by BFS depth, potentially affected tests, public API markers, and a statistics summary; passing since: 'main' can limit to files the branch actually touched. gp_index—refresh the index from within the agent, input { path? }, reindexes and invalidates the path-based query cache.
Privacy and security: local-first. No http, fetch, axios, or analytics imports in src/, enforced by ESLint rules plus meta-tests; no child_process, exec, or spawn; source code never leaves the local machine, and only structural metadata (names, locations, signatures, call relationships) is stored in ~/.graphpilot/; signatures are redacted before disk write for common secret patterns (OpenAI/Anthropic sk-, GitHub ghp_/ghs_, AWS AKIA, JWT, PEM headers, Slack/Stripe tokens); strict file permissions (directory 0o700, file 0o600); schema validation on load, with corrupted graphs falling back to "no index"; handwritten input validators for every MCP tool.
Limitations (v0.1): TS/JS only; Python, Rust, Go, and Java are not v1 scope, Python may be added in v0.2/v0.3 as needed; name-based parser (no import path tracing, no typed method dispatch), expected about 25–35% of edges resolve to in-repo symbols, the rest to the standard library/third party; no semantic search, gp_recall is name-only; no .graphpilotignore yet (by default skips node_modules, dist, build, .git, coverage, .next, .nuxt, .cache, out, *.d.ts); single query single repository, workspace abstraction is on the v1.x roadmap.
Other information: the repository License is Apache-2.0, copyright 2026 Akshay Sharma. For troubleshooting, you can run graphpilot doctor. Documentation includes docs/quickstart.md, docs/mcp-setup.md, docs/troubleshooting.md, docs/architecture.md, docs/limitations.md, bench/README.md, examples/. For security reports, please follow SECURITY.md.
