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.

A few query shapes that exercise the graph well, if you want to feel out what changed:

• Blast-radius questions — “What would break if I changed the return type of getSession()?” The index answers from call edges instead of grepping for the function name and reading every hit.
• Dead-code hunting — “Which exported functions in src/utils/ have no callers anywhere in the repo?” Without an index this is one of the most tool-call-expensive questions you can ask.
• Onboarding questions — “Walk me through what happens between an incoming request and the database write.” Cross-layer traces are where agents burn the most discovery reads on unfamiliar code.
• Import hygiene — “Which modules import directly from internal/ instead of going through the public API?” Structured import edges make this a single query.

Where the graph won’t help is just as predictable: questions about values and behavior (“why is this config flag false in production?”) still require reading actual file contents, and the agent will fall back to normal Read calls for those. The index removes discovery overhead; it doesn’t replace reading code.

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.

Upgrades have their own routine. Since v1.4.1 the CLI checks for newer releases in the background and tells you when one exists; apply it with codegraph upgrade, then run codegraph index once in each indexed project — the v1.6.0 release notes call this out explicitly, since schema changes between versions can otherwise leave a stale graph serving answers. (v1.6.0 also fixed the underlying drift problem, so a long-running index no longer diverges from a fresh one between upgrades.) Configuration changes are cheaper: edits to codegraph.json — including the deprioritize list — take effect without restarting the MCP server as of v1.6.0, so tuning what outranks what no longer means bouncing your agent session.

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 keeps disabling it, override with:

CODEGRAPH_FORCE_WATCH=1 codegraph serve --mcp

MCP server not connecting to Claude Code

Symptom: Claude Code shows CodeGraph in /mcp with a red or disconnected status. Sessions start without the MCP tools available.

Why (GitHub issue #172): Older CodeGraph builds used a custom stdio transport sending newline-delimited JSON. Claude Code implements the official MCP spec with Content-Length header framing — the same protocol as LSP. The handshake fails silently because the parser chokes on "Content-Length: 234" as if it were a JSON line.

Fix: Upgrade to v0.9.9, which replaces the custom transport with @modelcontextprotocol/sdk’s official StdioServerTransport:

npm i -g @colbymchenry/codegraph@latest
codegraph install    # rewrites agent config entries
# restart Claude Code

What’s Changed Since v0.9.9

This guide was written against v0.9.9 (June 2, 2026). The install commands are unchanged — npm i -g @colbymchenry/codegraph always pulls the latest — but the project has moved fast since, and two releases are worth knowing about before you install.

v1.5.0 (July 21, 2026) rebuilt the parsing engine in Rust. Parsing and symbol extraction for 20 languages now run in a compiled native kernel, with the previous engine kept as an automatic fallback for platforms without a prebuilt binary (graphs are verified byte-for-byte identical either way, and CODEGRAPH_KERNEL=0 disables the native path). The practical difference is sync speed: a file save now reaches the graph in roughly 0.3–0.4 seconds even on a 27,000-file repository, down from the 2-second debounce plus re-index of earlier versions. Indexing also became container-aware — worker pools size themselves from the container’s actual CPU and memory allowance instead of the host’s, which fixed out-of-memory failures on CI runners. The headline stress test: the Linux kernel (70,000 files, 2 million symbols) indexes to completion on a 2-core, 6GB machine in under 12 minutes. Releases are now cryptographically verifiable too — npm packages publish with provenance, and GitHub Release bundles carry signed attestations checkable with gh attestation verify.

v1.6.0 (August 26, 2026) added GitHub Copilot support and one-command setup. codegraph install now configures Copilot in VS Code, the Copilot CLI, and JetBrains IDEs alongside Claude Code, Cursor, Codex, and Gemini CLI. For containers and CI, codegraph install --yes --init wires up agents and indexes the project with no prompts. The release also fixed a disk-space leak where a force-killed session could leave the SQLite write-ahead log growing without bound (tens of gigabytes reported — the leftover log is now folded back and trimmed automatically on next open), added a deprioritize setting to keep helper folders from outranking real code in results, and made the MCP server find an indexed project when launched from a monorepo or workspace root above it. Quality-of-results work landed too: codegraph_explore stopped re-sending code it already showed the agent earlier in a session and now focuses responses on the symbols that answer the question — a direct token saving on long sessions, on top of the indexing gains.

In between, v1.3.0 (July 7, 2026) added Nix indexing — flakes, NixOS modules, overlays — which matters if your self-hosted stack is Nix-managed. If you installed at v0.9.x, run codegraph upgrade and re-run codegraph install so agent configs pick up the current server entry.

CodeGraph vs Serena: Static Graph or Live Language Server

The comparison people actually ask about — it’s literally issue #235 on the CodeGraph repo — isn’t the codegraph-ai fork in the table above. It’s Serena, the other widely deployed open-source MCP toolkit for making agents smarter about code. The two solve overlapping problems with opposite architectures.

CodeGraph pre-computes. It parses everything once with tree-sitter, stores a static symbol graph in SQLite, and answers “who calls this, what imports that, what breaks if I change this interface” from the index in one or two MCP calls. Read-oriented, whole-repo, fast at dependency and blast-radius questions.

Serena runs live tooling. Instead of an index, it hands the agent real Language Server Protocol capabilities — the same machinery behind IDE features. Its tools work at the symbol level: find_symbol and find_referencing_symbols for retrieval, and — this is the part CodeGraph doesn’t do at all — semantic editing operations like insert_after_symbol, so the agent modifies code by symbol reference rather than by rewriting text ranges. It supports 30+ languages through their language servers.

The practical split:

• Understanding a codebase, tracing dependencies, cutting discovery tool calls → CodeGraph. This is where the 58% tool-call reduction lives, and a static graph answers repo-wide structural questions faster than walking LSP references one hop at a time.
• Precision refactors and symbol-level edits → Serena. A multi-step rename-and-update-references becomes one atomic, LSP-verified operation instead of a series of text edits the model might fumble.
• Both at once → viable. They’re independent MCP servers and don’t conflict; some developers run CodeGraph for navigation and Serena for edits. The cost is context: every registered MCP server adds tool definitions to each request, so only keep both wired into an agent if you genuinely use both sides.

If you’re choosing one and your pain is “Claude Code burns 20 tool calls before answering an architecture question,” start with CodeGraph — it’s the one with published benchmarks for exactly that. If your pain is the agent botching mechanical refactors, start with Serena.

When NOT to Use CodeGraph

Repos under ~100 files: The index overhead is real. codegraph init takes 5–10 seconds even on small projects, and the MCP server uses 80–150 MB of memory. For a 30-file script collection, the agent’s direct file reads finish about as fast as a graph traversal.

Codebases heavy on runtime patterns: CodeGraph is static analysis only. It cannot track dynamic dispatch, runtime reflection, or metaprogramming — Python’s __getattr__, Ruby’s method_missing, Spring’s annotation-driven beans, JavaScript Proxy objects. If your codebase relies heavily on these patterns, the graph will be incomplete and the agent will still fall back to file reads for those paths.

Older Linux distributions: The CLI bundles a precompiled runtime, but it depends on glibc 2.17+. CentOS 7 and RHEL 7 will fail at install time.

Network filesystems (NFS, SMB) in production: The watcher uses inotify, which doesn’t fire for remote file changes. You’ll need to run codegraph index manually after file operations, or use git hooks.

Where This Fits in a Local AI Stack

CodeGraph is a middle layer — it improves any agent that reads codebases, regardless of what model powers it. If you’re pairing it with local models to eliminate API costs entirely, see the Continue.dev + Ollama setup guide for offline code completion, or the Aider setup guide for CLI-driven coding. For a broader view of which open-source coding agents are production-ready in 2026, see Open-Source Coding Agents 2026: Which One to Run.

For burst GPU workloads — fine-tuning, embedding large codebases, or running inference on models too big for your local hardware — RunPod remains the cheapest on-demand option. If you’re sizing permanent hardware for a local coding-model setup instead, the mini PC local LLM buyer’s guide at runaihome.com covers what $500–$1,500 machines can actually serve. And on the agent side, CodeGraph’s biggest beneficiaries are the agent-first IDEs — the Cursor 3 review at aicoderscope.com explains why parallel agents multiply exactly the kind of file-discovery tool calls this index eliminates.

FAQ

Does CodeGraph work with local models via Ollama or LM Studio?
Yes. CodeGraph is model-agnostic — it’s an MCP server that any agent can query. The reduction in tool calls applies regardless of which model the agent uses. Agents running local models through Continue.dev or Aider benefit equally to cloud-backed agents.

Will CodeGraph slow down my editor?
The MCP server runs as a background process. The file watcher uses native OS events and is debounced to 2 seconds, so it doesn’t add perceptible latency to saves. Memory usage is 80–150 MB depending on codebase size — comparable to a TypeScript language server. CPU usage is near zero between saves.

How do I update the index after a major refactor or branch switch?
Run codegraph index from the project root. This rebuilds from scratch and takes about 20–30 seconds on a 3k-file project. The live watcher handles incremental updates during normal development automatically.

Does it work on monorepos?
Yes. Run codegraph init from the monorepo root to index the full workspace, or from a package subdirectory to scope it to one package. Indexing a 50k-file monorepo takes several minutes for the first build. Per-package indexes are faster but miss cross-package call relationships.

Is there a .codegraphignore file?
Yes. CodeGraph respects .gitignore by default and skips files over 1 MB. For additional exclusions, add a .codegraphignore file in the project root using gitignore syntax.

Does CodeGraph work with GitHub Copilot?
Yes, since v1.6.0 (August 26, 2026). codegraph install configures Copilot in VS Code, the Copilot CLI, and JetBrains IDEs, alongside the previously supported Claude Code, Cursor, Codex CLI, and Gemini CLI. The same local index serves all of them.

What’s the current version of CodeGraph, and is this guide still accurate? v1.6.0 (August 26, 2026) is still the latest release as of this guide’s most recent check on October 28, 2026. The three install commands are unchanged since v0.9.9 — npm i -g @colbymchenry/codegraph always pulls the current release — so everything in the Install section applies as written. The “What’s Changed” section above covers the differences you’ll notice at runtime.

Do I need to rebuild the index after upgrading CodeGraph? Yes — run codegraph index once in each indexed project after an upgrade. The v1.6.0 release notes call this out directly: internal schema changes between versions can leave an old index answering from stale structure. It’s a one-time cost per project (seconds to a couple of minutes depending on repo size), and the background update check added in v1.4.1 means you’ll know when an upgrade is pending rather than discovering it from odd results.

Can I run CodeGraph and Serena at the same time? Yes. They’re separate MCP servers with no shared state — CodeGraph reads from its SQLite index, Serena talks to language servers. The trade-off is context overhead: each server’s tool definitions ride along on every agent request, so wire both into the same agent only if you use CodeGraph’s navigation and Serena’s semantic editing regularly. Otherwise pick the one matching your bottleneck (see the comparison section above).

Does CodeGraph send my code anywhere? No. The indexer, the SQLite database, and the MCP server all run on your machine — the graph lives in .codegraph/ in your project root, and queries never leave localhost. The only network-touching behavior in the current release is the opt-in Pro waitlist prompt, which sends nothing unless you type an email. Your code still goes to whatever model your agent uses, exactly as it did before — CodeGraph changes what the agent looks up locally, not where the model runs. For fully offline operation, pair it with a local model (see the Continue.dev and Aider guides linked above).

How much disk space does the index use? Modest. The SQLite graph for a 10k-file repository fits under 200 MB, and smaller projects use proportionally less. Add .codegraph/ to your .gitignore — the index is machine-local and rebuilds from source. One historical caveat: versions before v1.6.0 could leave the write-ahead log growing unbounded after a force-killed session; current releases trim it automatically on next open, so upgrade if you’re seeing a multi-gigabyte .codegraph/ directory.

Do I still need CodeGraph if Cursor already indexes my codebase? They index different things. Cursor’s built-in codebase indexing is embedding-based semantic retrieval — good at “find code related to authentication.” CodeGraph stores explicit symbol relationships — callers, imports, inheritance — which answers structural questions (“every caller of this function”) exactly rather than approximately. Cursor users get the most from CodeGraph on dependency-tracing and refactor-impact questions, where similarity search tends to return relevant-looking but incomplete results. For Claude Code, which has no built-in index at all, the case is more straightforward.

Is CodeGraph still free and open source?
The core project remains MIT-licensed and fully local. As of v1.5.0 there’s an opt-in waitlist for a “CodeGraph Pro” beta — the CLI asks once per machine after codegraph install or codegraph upgrade, sends nothing unless you type an email, and never asks in scripts or CI. Releases now publish with npm provenance and signed build attestations, so you can verify a package was built from the public repository.

Does CodeGraph index dependencies like node_modules or vendored code?

No. CodeGraph respects .gitignore by default, so node_modules/, build output, and anything else you’ve gitignored never enters the graph, and files over 1 MB are skipped regardless. That’s the behavior you want — indexing dependencies would balloon the SQLite database and flood symbol queries with library internals instead of your code. If you vendor dependencies that aren’t gitignored, exclude them explicitly with a .codegraphignore file using the same gitignore syntax.

What hardware does CodeGraph need?

Less than you’d guess, and no GPU — parsing and SQLite queries are plain CPU work. The MCP server holds 80–150 MB of memory depending on codebase size, about what a TypeScript language server costs, and sits near zero CPU between saves. The project’s own stress test indexes the Linux kernel — 70,000 files, 2 million symbols — to completion on a 2-core, 6 GB machine in under 12 minutes, and since v1.5.0 the worker pools size themselves from a container’s actual CPU and memory allowance, so it behaves on CI runners and resource-capped dev containers too. Any laptop that runs your editor runs CodeGraph.

How do I uninstall CodeGraph completely?

Three steps. Remove the package with npm uninstall -g @colbymchenry/codegraph, delete the .codegraph/ directory in each project you indexed (that’s the entire database — nothing lives outside it), and remove the codegraph entries from your agent configs: ~/.claude/mcp_servers.json for Claude Code and ~/.cursor/mcp.json for Cursor. The MCP server only runs while an agent session has it loaded, so there’s no daemon to stop and no cloud state to clean up.

Sources

• CodeGraph GitHub repository (colbymchenry/codegraph)
• CodeGraph CLAUDE.md — architecture and module guide
• GitHub issue #172: MCP Content-Length transport mismatch
• AIToolly: CodeGraph local knowledge graph for Claude Code and Cursor (May 26, 2026)
• Level Up Coding: “I gave Claude Code a map of my repo” — community benchmark
• codegraph-ai/CodeGraph: Extended 42-tool version
• knightli.com: What is CodeGraph? (May 23, 2026)
• CodeGraph CHANGELOG.md — full version history
• Release v1.5.0: the Rust engine release — GitHub
• Serena: semantic retrieval and editing MCP toolkit — GitHub (oraios/serena)
• Issue #235: key difference between CodeGraph and Serena — GitHub
• Serena vs Code Index vs CodeGraphContext vs ChunkHound — HeyClaude comparison

Guide originally written against v0.9.9 (June 8, 2026); version status re-checked October 28, 2026 — v1.6.0 (August 26) remains the current release.

What self-hosting actually costs

Real cost breakdowns for self-hosted AI: hardware floors, power, maintenance hours, and the honest comparison against paying for it. No spam, unsubscribe anytime.

Email address Subscribe