CodeGraph Setup Guide 2026: Cut Claude Code Tool Calls by 58%

By AIFoss · 10 min read
claude-codecursormcpcodegraphselfhostedai-coding

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/CodeGraphNo indexing (baseline)
Best forClaude Code, Cursor, Codex CLIVS Code extension usersRepos under ~100 files
Languages20+38+—
Token reduction (median)47%Not published—
Tool call reduction (median)58%Not published—
VS Code extensionNoYes—
LicenseMITNot 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):

CodebaseApprox. filesCostTokensSpeedTool calls
VS Code~10k-18%-64%-11%-81%
Django~3k-16%-47%-22%-58%
Median across 7 reposvarious-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 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

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.

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.

Sources

Was this article helpful?