Skip to content
JournalTORIS / FIELD NOTES

← BlogDeveloper tools

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.

#CodeGraph #MCP #Claude Code #Cursor #오픈소스 #개발도구

Read the Korean original

CodeGraph (v1.6.4): Local Code Knowledge Graph MCP Cutting Agent Tool Calls by 88%

Q. My AI coding agent like Claude Code or Cursor burns time and tokens running grep and reading files one by one. Is there a local way to give it the codebase structure in one shot? Initialize colbymchenry/codegraph once 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/codegraph GitHub repository (78,314 stars, 5,208 forks, MIT license) and the v1.6.4 release 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-sitter and incrementally syncs edits within ~300ms using native OS file events.
  • Single-tool MCP surface: Exposes codegraph_explore by default to prevent tool mis-picks and wires 19 agents—including Claude Code, Cursor, Codex CLI, and Hermes Agent—via codegraph 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.

Official colbymchenry/codegraph GitHub repository page

Advertisement

Architecture and official benchmark numbers

CodeGraph combines a native Rust parser, a local SQLite FTS5 database, and OS-level incremental file watching.

  1. Extraction: A compiled Rust kernel parses 20 languages using tree-sitter grammars to extract symbol nodes and relationship edges.
  2. 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).
  3. 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)

CodeGraph architecture compared with traditional file-by-file agent search

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.

Developer desk setup displaying a local code dependency graph and terminal

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_ROOT includes, newer Kotlin syntax, and prevents git index.lock contention 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-only to keep .codegraph/ out of git, and run codegraph telemetry off if you prefer zero anonymous usage telemetry. For related local-first tooling, see Toris Studio services or our MarkItDown local document MCP guide.

Sources

Advertisement