This article was originally published on aifoss.dev
TL;DR: CodeGraph v0.9.9 is a local MCP server that pre-indexes your codebase using tree-sitter and SQLite, then serves a symbol knowledge graph to Claude Code and Cursor instead of letting the agent grep and read files on every query. Official benchmarks across seven real codebases show 58% fewer tool calls, 47% fewer tokens, and 16% lower API cost — validated on Claude Opus 4.8 on June 2, 2026. Three install commands. MIT license. Nothing leaves your machine.
What you'll have running after this guide:
- CodeGraph's MCP server wired into Claude Code and/or Cursor
- Your codebase pre-indexed into a local SQLite knowledge graph
- Incremental re-indexing on every file save via native OS file events
| CodeGraph (colbymchenry) | codegraph-ai/CodeGraph | No indexing (baseline) | |
|---|---|---|---|
| Best for | Claude Code, Cursor, Codex CLI | VS Code extension users | Repos under ~100 files |
| Languages | 20+ | 38+ | — |
| Token reduction (median) | 47% | Not published | — |
| Tool call reduction (median) | 58% | Not published | — |
| VS Code extension | No | Yes | — |
| License | MIT | Not stated | — |
Honest take: For Claude Code and Cursor users, the colbymchenry build is the one to install. It has public benchmarks, active development (v0.9.9 released June 2, 2026), and a one-command installer that auto-configures both agents. Switch to codegraph-ai only if the VS Code extension matters more than verified numbers.
Why Claude Code Reads So Many Files
When you ask Claude Code "how does the auth middleware validate JWT tokens?" the agent has no map of your project. It reads files, runs greps, follows imports, reads more files. On a 1,000-file TypeScript codebase, answering one architecture question might burn 15–30 tool calls before the agent has gathered enough context to respond.
This is expected behavior for a file-reading agent operating without a pre-built index. It explores the code graph at query time, which is slow and burns tokens. The larger the repo, the worse the exploration overhead scales.
CodeGraph solves this by building the graph before the session starts. Instead of file reads and greps, Claude Code issues 1–3 structured MCP calls to a local SQLite database and gets back symbol relationships, call chains, and import maps directly.
How the Index Works
Three components run locally:
tree-sitter parses every source file into an AST. Language-specific queries extract nodes (functions, classes, methods, interfaces) and edges (call relationships, import chains, inheritance hierarchies). Supported languages include TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Lua, Luau, and Pascal/Delphi — 20+ in total.
SQLite with FTS5 stores the extracted graph at .codegraph/codegraph.db in your project root. The FTS5 full-text search extension handles queries like "find all usages of UserService" in sub-millisecond time, without file scanning. The index for a 10k-file VS Code repo fits under 200 MB.
An MCP server wraps the database and exposes tools to your agent. The server watches the project directory using native OS file events (FSEvents on macOS, inotify on Linux) with a 2-second debounce window. When you save a file, only that file re-indexes — incremental updates typically finish in under 100 ms.
The MCP server also sends its full instruction set to Claude Code at startup via src/mcp/server-instructions.ts, so Claude Code learns how to query the graph effectively without you modifying your CLAUDE.md.
Benchmarks
CodeGraph's official benchmarks run against seven real open-source codebases, re-validated on Claude Opus 4.8 on June 2, 2026 (v0.9.9):
| Codebase | Approx. files | Cost | Tokens | Speed | Tool calls |
|---|---|---|---|---|---|
| VS Code | ~10k | -18% | -64% | -11% | -81% |
| Django | ~3k | -16% | -47% | -22% | -58% |
| Median across 7 repos | various | -16% | -47% | -22% | -58% |
The VS Code numbers are the ceiling case — 81% fewer tool calls because larger repos accumulate the most file-discovery overhead without an index. The gains shrink as repo size drops. Below roughly 100 files you'll see minimal improvement.
Independent community data: a developer testing across four private repositories found a median of 70% fewer tool calls, 59% fewer tokens, and 49% faster response time (source).
Install
Prerequisites
CodeGraph v0.9.9 requires Node.js 22+ for programmatic library use. The CLI and MCP server bundle their own runtime, so a global install works without managing a Node version manually. If you're upgrading from a pre-0.9 release on Node 24, reinstall from scratch to pull updated native SQLite bindings.
Run codegraph status after install to confirm the backend is native, not wasm:
Backend: native (sqlite3 v5.1.7) ← good
Backend: wasm ← reinstall needed
Three commands
# 1. Install globally
npm i -g @colbymchenry/codegraph
# 2. Register with your agents
codegraph install
# 3. Initialize the index in your project
cd /path/to/your/project
codegraph init
codegraph install auto-detects which agents are installed and writes the MCP server config into each one's settings file:
✓ Claude Code → ~/.claude/mcp_servers.json updated
✓ Cursor → ~/.cursor/mcp.json updated
Codex CLI → not found, skipped
Gemini CLI → not found, skipped
codegraph init creates .codegraph/ in the project root and builds the first graph. On a 3k-file Python project, expect 10–30 seconds. A 10k-file TypeScript repo takes up to 2 minutes. After init finishes, restart Claude Code or Cursor so they load the new MCP configuration.
Your First Query With the Index
Once Claude Code starts with the MCP server active, check /mcp — you should see codegraph listed with a green status. Then ask something that would normally trigger a long discovery chain:
> How does the auth middleware validate JWT tokens in this repo?
Without CodeGraph, this might produce 15+ Read and Grep tool calls. With the index, the agent issues 1–3 codegraph MCP calls — fetching the symbol subgraph for the authentication module — and answers from structured data.
You'll notice the difference most on cross-file questions: data flow from API handler to database layer, which services a module calls, what breaks if you change a shared interface.
Ongoing Index Management
The file watcher handles most updates automatically. For explicit control:
# Rebuild the full index (after major branch switches or large merges)
codegraph index
# Check index health
codegraph status
Expected codegraph status output on a healthy setup:
Backend: native (sqlite3 v5.1.7)
Journal: wal
Files: 3,247 indexed
Symbols: 41,892
Edges: 187,045
Watcher: active
If Journal shows anything other than wal, you're on a filesystem that doesn't support WAL mode — see the WSL2 issue below.
Two Problems You'll Hit
WSL2 /mnt path causes database lock contention
Symptom: codegraph status shows Journal: other than wal. The MCP server occasionally hangs or returns stale results.
Why: CodeGraph opens SQLite in WAL (write-ahead logging) mode for concurrent reads and writes from the watcher and MCP server. WSL2 /mnt paths and network shares don't support WAL, causing lock contention.
Fix: Move the project to a native Linux path (~/projects/myapp instead of /mnt/c/projects/myapp). If you can't move it, disable the file watcher and let git hooks handle re-indexing:
CODEGRAPH_NO_WATCH=1 codegraph serve --mcp
CodeGraph will offer to install post-commit and post-merge git hooks that re-index after each commit. For cases where the watcher is fast enough but WSL auto-detect kee
Top comments (0)