Table of Contents
CodeGraph for Claude Code: 92% Fewer Tool Calls With One npm Command (May 2026)
On May 17, 2026, CodeGraph crossed 3,270 GitHub stars. 857 of those came in a single day. The reason: developers running Claude Code on large codebases discovered a measurable problem with how Claude's Explore agent navigates unfamiliar code by default, and CodeGraph fixes it with one install command.
The short version: CodeGraph is an open-source MCP server that pre-indexes your codebase into a local SQLite knowledge graph, then hands Claude Code eight purpose-built tools to query it. The result across six real-world codebases is 92% fewer tool calls and 71% faster exploration. Nothing leaves your machine. MIT license, no paid tier.
This guide covers installation, what each of the eight MCP tools does, how to keep the graph current, and when CodeGraph is the right call versus a well-written CLAUDE.md.
What CodeGraph does and why the numbers matter
The Explore agent's default behavior
Claude Code's Explore agent navigates code the way a developer would if they had no prior context: it searches filenames, reads files, grep-searches for symbol definitions, then follows references outward. Each step is a separate tool call. On a codebase with 50,000 lines spread across 400 files, a single "what calls this function?" question might cost 30 or more tool calls before Claude has enough context to answer confidently.
That's not a bug. It's what the agent does without a better signal.
What a knowledge graph changes
A pre-built knowledge graph short-circuits that loop. Instead of assembling context file by file at query time, Claude asks the graph directly: "give me all callers of processPayment in the orders package." The graph answers in one call with a structured result. Claude moves to reasoning instead of crawling.
The practical difference shows up in the benchmark numbers below. One query that took 34 tool calls against the VS Code repo drops to 2. On the Swift Compiler (25,874 files), a full architectural exploration run goes from 37 tool calls to 6.
The benchmark across six codebases
CodeGraph's README documents benchmark runs across six production codebases, covering TypeScript, Swift, and mixed-language projects:
| Codebase | Files | Tool calls without | Tool calls with | Reduction |
|---|---|---|---|---|
| VS Code | ~8,000 | 34 | 2 | 94% |
| Excalidraw | ~600 | 18 | 3 | 83% |
| Claude Code repo | ~900 | 22 | 4 | 82% |
| Alamofire | ~200 | 14 | 2 | 86% |
| Swift Compiler | 25,874 | 37 | 6 | 84% |
| Average across runs | -- | -- | -- | 92% |
The exploration time reduction averages 71%. Both numbers come from the CodeGraph GitHub README and reflect the delta between baseline Claude Code Explore runs and runs with the MCP server active.
Installing CodeGraph as an MCP server
Prerequisites: Node 18+, existing Claude Code setup
You need Node.js 18 or later and a working Claude Code installation. Confirm your Node version before running the installer:
node --version
# Should output v18.x.x or higherCodeGraph does not need an API key. It runs entirely locally.
Run npx @colbymchenry/codegraph
The npx command pulls the installer package and launches an interactive setup that configures the MCP server in your Claude Code settings automatically:
npx @colbymchenry/codegraphThe installer adds the MCP server entry to ~/.claude/mcp_servers.json (or the equivalent config path for your platform). You don't need to edit JSON by hand.
Initialize your project: codegraph init -i
From your project root, run the interactive initializer:
cd /path/to/<YOUR_PROJECT>
codegraph init -iThe -i flag opens a prompt asking which directories to include, which to exclude, and whether to enable the file watcher. For most TypeScript or Python projects, the defaults work without changes.
Run the first full index: codegraph index
codegraph indexThis is the slow step. CodeGraph parses every file in the included directories, resolves imports and call graphs, and writes the result to .codegraph/codegraph.db. On a 50,000-line TypeScript monorepo, expect 30-90 seconds on the first run. Subsequent incremental syncs take under 5 seconds.
Add .codegraph/ to your .gitignore. The database is local and machine-specific:
echo ".codegraph/" >> .gitignoreRestart Claude Code and confirm MCP server is active
Restart Claude Code entirely (not just reload the window). Then open a chat and type:
/mcpYou should see codegraph listed as a connected server with all 8 tools available. If it shows as disconnected, run codegraph status in the terminal to check the database health, then restart again.
The eight MCP tools and when to use each
codegraph_search
codegraph_search finds symbols by name across the full index. Pass a partial or full symbol name and the tool returns matching functions, classes, types, and files with their locations.
Use this first when you know what you're looking for but not where it lives. Claude reaches for it the way you'd use "Go to Definition" in an IDE, but across the entire codebase in one shot.
{
"tool": "codegraph_search",
"input": { "query": "processPayment", "type": "function" }
}codegraph_context
codegraph_context builds a task-relevant code context window. You describe what you're trying to do in natural language, and the tool returns the symbols, files, and relationships most relevant to that task.
This is the tool that accounts for most of the tool-call reduction in the benchmarks. A task like "add retry logic to the payment flow" used to require 10-15 individual file reads; codegraph_context collapses that into one structured response.
codegraph_callers and codegraph_callees
These two work as a pair. codegraph_callers returns every location in the codebase that calls a given function or method. codegraph_callees returns everything a given function calls.
Both are essential for impact analysis before a refactor. Run codegraph_callers on the function you're about to change and you'll know exactly what breaks before touching a line of code.
# Example: Claude internally calls something like:
# codegraph_callers({ symbol: "validateUserSession", depth: 2 })
# Returns: 14 call sites across 6 filescodegraph_impact
codegraph_impact is the higher-level version of callers/callees analysis. Pass a symbol or file, and it returns a ripple map: everything that directly or transitively depends on that target. Claude uses this before large refactors to scope the blast radius.
On the VS Code codebase benchmark, replacing a manual file-by-file impact trace with codegraph_impact is what drove the tool-call count from 34 to 2.
codegraph_node, codegraph_files, codegraph_status
Three utility tools:
codegraph_node returns full metadata for a single symbol: type signature, file location, doc comment, exported/internal status, and the list of callers and callees in condensed form. Useful when Claude needs precise details on one specific symbol without pulling in the broader context window.
codegraph_files retrieves the file and directory structure of the indexed codebase, optionally filtered by path pattern or file type. It gives Claude an architectural map without opening individual files.
codegraph_status reports the health of the index: last sync time, file count, whether the file watcher is running, and any files that failed to parse. Run it if exploration results feel stale or incomplete.
Keeping the graph in sync
The file watcher (FSEvents/inotify/ReadDirectoryChangesW)
CodeGraph uses native OS file system events to keep the index current. On macOS it hooks into FSEvents, on Linux into inotify, and on Windows into ReadDirectoryChangesW. Changes trigger a debounced incremental sync so the database stays within seconds of your working state.
The watcher starts automatically if you enabled it during codegraph init -i. Confirm it's running:
codegraph status
# File watcher: active
# Last sync: 2 seconds ago
# Indexed files: 1,847codegraph sync vs codegraph index for large monorepos
For codebases under 5,000 files, the watcher handles everything. For large monorepos (we've seen this matter at the 50,000-file range), the two commands serve different purposes:
codegraph sync runs an incremental update, processing only files changed since the last index. Fast. Run this if the watcher missed a bulk operation like a branch switch or a large merge.
codegraph index rebuilds the full graph from scratch. Slow but complete. Run it after switching to a branch with significant structural differences, or if codegraph status reports parse errors on a meaningful share of files.
For teams running Claude Code on a remote VPS and hosting codegraph serve --mcp as a shared service, a DigitalOcean droplet or a Cloudways server gives you a persistent process that keeps the graph warm across sessions without running the index locally on each developer's machine.
Database size on large monorepos
The .codegraph/codegraph.db file grows roughly linearly with file count. Rough estimates per CodeGraph's own README benchmark codebases:
- Excalidraw (~600 files): ~12 MB
- VS Code (~8,000 files): ~180 MB
- Swift Compiler (25,874 files): ~620 MB
The database sits in .codegraph/ at the project root. Exclude it from version control and from any build or sync process that would copy it unnecessarily.
CodeGraph vs. a well-written CLAUDE.md
What CLAUDE.md handles
A CLAUDE.md is a project briefing. It runs once, before Claude starts work on a task. Use it to tell Claude what the project is, what conventions to follow, which files to avoid, how to run tests, and what the architecture looks like at a high level.
CLAUDE.md is static. It does not update when you add a file or rename a function. It's a new engineer's onboarding doc. Useful, but it doesn't replace live search.
What CodeGraph handles
CodeGraph is a live navigation layer that Claude queries while it works. Every call to find a function, trace a call path, or scope a refactor goes to the graph. The graph reflects the current state of the repo, not a snapshot you wrote last month.
CLAUDE.md is the briefing before work starts. CodeGraph is the navigation layer during it.
Run both
A strong CLAUDE.md paired with CodeGraph gives Claude a running start and fast navigation on every subsequent query. Neither replaces the other. If you're already seeing value from a detailed CLAUDE.md, CodeGraph adds query speed on top. If you've been running without either, start with CodeGraph since the install is faster and the benchmark gains are immediate.
Teams using GitHub Copilot in parallel see the same benefit: faster code exploration cuts context-assembly overhead regardless of which AI tool is running. The GitHub Copilot App setup guide covers the complementary patterns.
Language and framework support
19 languages out of the box
CodeGraph's parser supports: TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi (counted as two dialect variants), and two additional experimental languages in the 2026-05 build.
That list covers the majority of professional codebases. The parser handles mixed-language monorepos without configuration, detecting language per file rather than assuming a single stack.
13 web frameworks for routing patterns
Framework-aware parsing improves routing context specifically. The 13 frameworks with dedicated support:
Django, Flask, FastAPI, Express, Laravel, Rails, Spring, Gin, chi, gorilla/mux, Axum, SvelteKit, and React Router.
For these frameworks, CodeGraph understands routing conventions and includes route-to-handler mappings in the graph. That means codegraph_context can answer questions like "which handler processes POST /api/payments" in one call rather than requiring a file scan.
FAQ
Does CodeGraph send any code to an external server?
No external services, APIs, or data leaving your machine. The graph lives in .codegraph/codegraph.db.
Does it work with Cline or Cursor, or only Claude Code?
CodeGraph's MCP server connects to any MCP-compatible client. Cline supports MCP tool sources per the @cline/sdk release on May 13, 2026, so CodeGraph's tools are accessible from Cline agents the same way they're accessible from Claude Code. Cursor's MCP support is in active development; check the Cursor changelog for current status.
How do I update CodeGraph?
npx @colbymchenry/codegraph@latestRunning the installer again updates the binary and re-registers the MCP server config. Your .codegraph/codegraph.db is preserved. Re-run codegraph index after a major version bump to pick up any schema changes.
Does indexing a 500k+ line monorepo cause performance issues?
The initial index on a 500,000-line codebase takes several minutes and spikes CPU during parsing. Once complete, the file watcher and incremental sync (codegraph sync) are low-overhead. The index process respects available cores; it won't saturate a machine with other workloads. If the initial index is blocking, run it during off-hours or in a CI step.
MIT license: can my company use this in proprietary projects?
Yes. MIT allows commercial use, modification, and distribution without requiring you to open-source your own code. The license does not restrict embedding CodeGraph in a proprietary workflow or a commercial product. Confirm with your legal team for any specific enterprise context, but the MIT license text itself has no commercial restrictions.