CodeGraph (v1.6.4): Local Code Knowledge Graph MCP Cutting Agent Tool Calls by 88%
How colbymchenry/codegraph uses a Rust kernel and SQLite FTS5 to cut AI agent tool calls by 88% and cost by 44%, plus the context-occupancy trade-off to watch.

Q. My AI coding agent like Claude Code or Cursor burns time and tokens running
grepand reading files one by one. Is there a local way to give it the codebase structure in one shot? Initializecolbymchenry/codegraphonce in your project and its Rust kernel indexes symbols and call edges into a local SQLite database (.codegraph/codegraph.db). Your agent then uses a single MCP tool,codegraph_explore, to retrieve exact source code, call paths, and blast radius in one call—cutting tool calls by 88%, response time by 53%, processed tokens by 62%, and cost by 44% across seven open-source benchmark repos (re-measured August 2026).
⚠️ Accuracy guardrail: This article was verified on November 22, 2026 against the official
colbymchenry/codegraphGitHub repository (78,314 stars, 5,208 forks, MIT license) and thev1.6.4release notes published on November 20, 2026. Benchmark figures reflect headless Claude Opus 4.8 runs across seven repositories; actual savings vary by model, query complexity, and codebase size.
30-second summary
- 100% local code knowledge graph: Stores functions, classes, call edges, inheritance, and routes in
.codegraph/codegraph.db(SQLite + FTS5) with no external APIs or keys. - Rust kernel with auto-sync: Parses 20 languages in compiled Rust via
tree-sitterand incrementally syncs edits within ~300ms using native OS file events. - Single-tool MCP surface: Exposes
codegraph_exploreby default to prevent tool mis-picks and wires 19 agents—including Claude Code, Cursor, Codex CLI, and Hermes Agent—viacodegraph install. - Important trade-off: While processed tokens drop by 62%, returning rich verbatim payloads increases persistent context-window occupancy by roughly 80% at the end of multi-turn sessions.
The problem CodeGraph solves: file discovery overhead
Before an AI coding agent edits a single line, it spends most of its time and budget rediscovering codebase structure. Without a graph, agents chain grep, glob, and file Read calls to reconstruct dependencies manually. In the repository's benchmarks, answering a single architecture question required up to 43 tool calls and 19 file reads.
CodeGraph shifts that discovery work upfront into a one-time index. Because symbols, call edges, and dynamic-dispatch hops (callbacks, React re-renders, interface-to-implementation links) are already resolved, the agent receives surgical context in one round trip instead of crawling files.

Architecture and official benchmark numbers
CodeGraph combines a native Rust parser, a local SQLite FTS5 database, and OS-level incremental file watching.
- Extraction: A compiled Rust kernel parses 20 languages using
tree-sittergrammars to extract symbol nodes and relationship edges. - Storage & Resolution: Everything lives in
.codegraph/codegraph.db, resolving cross-file imports, inheritance, and routes across 20+ web frameworks (Express, FastAPI, NestJS, Next.js, Elysia, and more). - Auto-Sync: Native file watchers (FSEvents, inotify, ReadDirectoryChangesW) debounce saves by 300ms and re-sync only changed files.
| Metric | VS Code (TS) | Excalidraw (TS) | Tokio (Rust) | Django (Python) | 7-Repo Average |
|---|---|---|---|---|---|
| Tool calls (with vs without) | 2 vs 28 | 2 vs 43 | 3 vs 29 | 3 vs 14 | 88% fewer |
| File reads | 0 vs 12 | 0 vs 18 | 0 vs 19 | 0 vs 8.5 | Cut to zero |
| Latency | 58s vs 2m 10s | 45s vs 2m 42s | 1m 3s vs 2m 43s | 54s vs 1m 23s | 53% faster |
| Tokens / Cost savings | 77% / 71% | 84% / 78% | 65% / 64% | 41% / 13% | 62% / 44% saved |
(Source: Official colbymchenry/codegraph README, median of 4 runs on Claude Opus 4.8, August 5, 2026)

There is one clear caveat in the official benchmarks: throughput drops sharply, but persistent context footprint grows. Because codegraph_explore returns verbatim source snippets and call flows in a single payload, end-of-session context occupancy on VS Code reached 67k tokens versus 18k tokens for file-reading agents (about 80% higher on average). Budget for that if you run long multi-turn sessions on smaller context windows.
Three-step setup from CLI to MCP
No manual build steps or config files are needed—three commands install the CLI, wire your agents, and build the graph.
# 1) Install the standalone CLI (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 2) Auto-detect installed agents (Claude Code, Cursor, Codex CLI, etc.) and wire MCP
codegraph install
# 3) Initialize the local knowledge graph in your repository
cd your-project
codegraph init
By default, the MCP server exposes only codegraph_explore. Testing showed that giving agents one capable tool reduces mis-selections and saves prompt tokens compared to listing eight narrow tools. If you need granular tools (node, search, callers, impact), you can re-enable them via CODEGRAPH_MCP_TOOLS.
For CI pipelines and pre-commit hooks, codegraph affected traces transitive imports from modified files (git diff --name-only | codegraph affected --stdin --quiet) so you only run impacted tests—pairing well with automated reliability workflows like our OpenSRE CI/CD reliability agent guide.

What changed in v1.6.4 and practical takeaways
Released on November 20, 2026, v1.6.4 sharpens single-symbol queries, Claude Code speed, and shared-host security.
- Leaner single-symbol answers: Queries such as
"who calls toValidURL?"now return only the target symbol definition and exact usage lines instead of padding the response with unrelated files. - Faster Claude Code hook: The prompt hook queries the already-running CodeGraph background server directly instead of reloading the index per prompt.
- User verification on shared machines: Agent sessions now verify that the background server process belongs to the current user before sending queries.
- Expanded language/framework support: Adds Elysia (Bun) routes, PHP
DOCUMENT_ROOTincludes, newer Kotlin syntax, and preventsgitindex.lockcontention during background sync.
If you upgrade an existing installation with codegraph upgrade, run codegraph index in each repository so new indexing improvements take effect.
Toris's take
- When to adopt immediately: You work in multi-file TypeScript, Python, Go, or Rust repositories—especially monorepos—with Claude Code, Cursor, or Codex CLI and want faster answers with far fewer discovery turns.
- When to skip or watch out: Tiny repositories with under 20 files gain little, and long sessions on tight context budgets should account for larger persistent tool outputs.
- Recommended setup: Run
codegraph init --local-onlyto keep.codegraph/out of git, and runcodegraph telemetry offif you prefer zero anonymous usage telemetry. For related local-first tooling, see Toris Studio services or our MarkItDown local document MCP guide.
Sources
Advertisement