What Is CodeGraph? Why It Matters and How to Use It — A Beginner-to-Advanced Guide (2026)

Quick answer: CodeGraph is a local, open-source (MIT-licensed) code-intelligence tool that parses your codebase with tree-sitter, stores every symbol, file, and relationship (calls, imports, references) in a local SQLite database, and exposes that structure to AI coding agents — Claude Code, Cursor, Codex CLI, Gemini CLI, and others — over the Model Context Protocol (MCP). Instead of an agent grepping and re-reading files every session to figure out how code connects, it asks CodeGraph one question and gets back the relevant source plus the call paths between symbols. Independent 2026 benchmarks put the gain at 88% fewer tool calls and 53% faster answers on average, with everything running 100% on your machine.

What Is CodeGraph, Exactly?

CodeGraph (open-sourced by developer Colby McHenry as @colbymchenry/codegraph) is a pre-indexed knowledge graph of a codebase. It has three moving parts: a native Rust kernel that parses source files using tree-sitter grammars, a local SQLite database (with FTS5 full-text search) that stores the resulting symbols, files, and edges, and an MCP server that hands that graph to AI agents on request. When you run it inside a project, it creates a .codegraph/ directory holding the index, and a background file watcher keeps that index in sync every time you or your agent edit a file.

The core idea is that a codebase is really a graph — functions call other functions, files import other files, routes map to handlers — and an AI agent that has to rediscover that graph by grepping and reading files on every session is doing redundant work. CodeGraph builds the graph once, keeps it fresh automatically, and lets the agent query it directly.

Why CodeGraph Matters

The problem CodeGraph targets isn't model intelligence — it's navigation. An AI coding agent working from raw grep and file reads has to rediscover a codebase's structure from scratch in nearly every conversation: which function calls which, what a class is used by, where a route handler actually lives. That discovery phase burns tool calls, tokens, and time before the agent even reaches the code it needs to look at.

A 2026-08-05 benchmark run across seven open-source codebases (VS Code, Excalidraw, Django, Tokio, OkHttp, Gin, and Alamofire), using Claude Opus 4.8 headlessly with the same architecture question asked per repo, measured the gap directly:

Codebase	Language	With CodeGraph	Without	Cost difference
VS Code	TypeScript	2 calls, 58s	28 calls, 2m 10s	71% cheaper
Excalidraw	TypeScript	2 calls, 45s	43 calls, 2m 42s	78% cheaper
Django	Python	3 calls, 54s	14 calls, 1m 23s	13% cheaper
Tokio	Rust	3 calls, 1m 3s	29 calls, 2m 43s	64% cheaper
OkHttp	Java	1 call, 33s	6 calls, 58s	21% cheaper
Gin	Go	1 call, 28s	7 calls, 46s	~even
Alamofire	Swift	4 calls, 54s	33 calls, 2m 22s	57% cheaper

Averaged across every repo: 88% fewer tool calls, 53% faster answers, 62% fewer tokens processed, 44% lower cost, and zero file reads on every single benchmark repo when CodeGraph was available. The catch worth knowing: CodeGraph's dense single-payload responses leave roughly 80% more token footprint resident in context at once (67k vs 18k tokens on the VS Code test) than the many small results a grep-based agent produces — a real tradeoff in long, small-context-window sessions, even though total tokens processed is lower.

An earlier six-project measurement from the tool's own documentation reported a similar pattern: on VS Code specifically, answering how the extension host talks to the main process took 52 tool calls without CodeGraph versus 3 with it; averaged across six projects, 92% fewer tool calls and 71% faster exploration.

Beginner's Guide: Installing CodeGraph and Running Your First Index

Getting started is three commands. No Node.js is required — the installer ships a self-contained bundle for macOS, Linux, and Windows on both x64 and arm64.

Install the CLI.
```
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
```
(Windows: irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex in PowerShell, or npm i -g @colbymchenry/codegraph on any OS.)
Wire it up to your AI agent.
```
codegraph install
```
This auto-detects and configures Claude Code, Cursor, Codex CLI, opencode, Gemini CLI, Antigravity, Kiro, Hermes Agent, and GitHub Copilot (VS Code, CLI, JetBrains) by writing MCP server configuration. It does not index any code yet — that happens per project.
Initialize the project you're working in.
```
cd your-project
codegraph init
```
This creates a .codegraph/ directory and builds the full graph in one step. From this point on, a native file watcher (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows) keeps the index in sync automatically, with a 2-second debounce so it doesn't re-index mid-keystroke.
Check it worked.
```
codegraph status
codegraph ui
```
status reports index health and any pending syncs; ui opens an interactive graph viewer at http://127.0.0.1:4747 so you can see what got indexed before trusting an agent to use it.

Once initialized, you generally don't run CodeGraph commands directly — your AI agent calls its MCP tool (named codegraph_explore) automatically whenever it needs to understand code, the same way it would otherwise reach for grep.

Intermediate: The Everyday Commands

Command	Purpose
`codegraph init [path]`	Initialize a project and build the graph
`codegraph sync [path]`	Manual incremental update (rarely needed — the watcher handles this)
`codegraph status [path]`	Show index statistics and pending syncs
`codegraph ui [path]`	Open the browser graph viewer
`codegraph explore <query>`	Get relevant symbols plus the call paths between them, from the shell
`codegraph query <search>`	Search symbols by name
`codegraph callers <symbol>`	Find everything that calls a function
`codegraph callees <symbol>`	Find everything a function calls
`codegraph impact <symbol>`	Analyze the blast radius of a change
`codegraph upgrade [version]`	Update to the latest release
`codegraph uninstall`	Remove CodeGraph from all agents and the CLI

CodeGraph parses 30 languages with identical treatment — full structural extraction and cross-file resolution into one graph, no per-language setup — including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, and even less common targets like COBOL, Solidity, Terraform, and Visual Basic .NET. It also emits framework-aware route nodes for 17 backend frameworks (Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, Axum, and more) and tracks client-side navigation for 8 routers (Next.js, React Router, Vue Router, SvelteKit, Expo Router, and others), so an agent can trace a request from an HTTP route through to its handler and back.

Advanced: Configuration, Tuning, and Embedding CodeGraph as a Library

CodeGraph is zero-config by default — node_modules, vendor, dist, build, .venv, files in .gitignore, and anything over 1 MB are excluded automatically. For finer control, an optional codegraph.json at the project root supports:

{
  "exclude": ["static/", "**/vendor/**"],
  "include": ["Tools/", "Local/typescript/"],
  "deprioritize": ["optional-skills/", "scripts/"],
  "extensions": { ".dota_lua": "lua", ".tpl": "php" }
}

Ranking precedence is include > exclude > deprioritize > the auto-defaults. A handful of environment variables tune the more demanding deployments: CODEGRAPH_WATCH_DEBOUNCE_MS (default 2000ms) controls how long the file watcher waits before re-indexing a burst of edits; CODEGRAPH_WAL_VALVE_MB and CODEGRAPH_WAL_HEAL_MB tune SQLite's write-ahead log size on very large repos; CODEGRAPH_NO_DAEMON disables the background daemon, useful on WSL2 setups where a Windows-mounted drive causes file-watching issues. At scale, CodeGraph indexed the Linux kernel — 70,000 files, roughly 2 million symbols, 6.4 million relationships — in under 12 minutes on a 2-core, 6GB VPS, and the Swift compiler's own 27,000-file repo in about 100 seconds initially, with ~4-second incremental updates per edit after that.

By default, only the combined codegraph_explore MCP tool is exposed to keep an agent's tool list short; the more granular tools (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) can be re-enabled explicitly:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers codegraph serve --mcp

CodeGraph can also be embedded directly as a library (Node 22.5+) instead of run as an MCP server, for teams building their own tooling on top of the graph:

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');
await cg.indexAll({ onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`) });

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true });
const impact = cg.getImpactRadius(results[0].node.id, 2);

On privacy and trust: the local database and browser UI (codegraph ui) bind only to 127.0.0.1, never send code externally, and require no account. Anonymous usage telemetry (which commands and languages are used, never code, paths, or file/symbol names) is on by default and can be disabled with codegraph telemetry off or the standard DO_NOT_TRACK=1 environment variable. Release artifacts are signed with SLSA v1.0 Build Level 2 attestations, and npm packages use trusted OIDC publishing — both independently verifiable rather than taken on faith.

How CodeGraph Compares to Other Code Indexing Tools

CodeGraph sits in the "knowledge graph engine" tier of a broader category that also includes symbol-level tools like Serena, embedding-based search like grepai and claude-context, and context-packing tools like Repomix. Each takes a different tradeoff between setup cost, precision, and what it can do beyond search (Serena, for instance, can also perform symbol-level renames). For a full breakdown of where CodeGraph fits against that wider field, see the further-reading link below.

Troubleshooting Common Issues

Symptom	Fix
"CodeGraph not initialized"	Run `codegraph init` in the project root
Indexing is slow	Confirm `node_modules`/build output is actually excluded; add `--quiet`
"Database locked" errors	Update to the latest release (bundled runtime + WAL mode fixes this), or move the project off a network-mounted drive
MCP server won't connect	Verify `.codegraph/` exists, then re-run `codegraph install`
A symbol seems missing	Wait ~2 seconds for auto-sync, run `codegraph sync` manually, or confirm the language is supported
WSL2 + Windows-drive issues	Set `CODEGRAPH_NO_DAEMON=1`, or move the project to a Linux-native filesystem

FAQ

What is CodeGraph in simple terms?

It's a local tool that reads your entire codebase once, builds a map of how every function, file, and class connects to every other one, and gives that map to your AI coding assistant so it doesn't have to rediscover the codebase's structure through trial-and-error file searches every time you ask it something.

Is CodeGraph free and open source?

Yes. It's released under the MIT license and distributed as @colbymchenry/codegraph on npm, with the source on GitHub.

Which AI coding agents work with CodeGraph?

Claude Code, Cursor, Codex CLI, opencode, Gemini CLI, Antigravity IDE, Kiro, Hermes Agent, and GitHub Copilot (VS Code, CLI, and JetBrains) via its MCP server, plus any other MCP-compatible client.

Does my code ever leave my machine?

No. Indexing, storage, and the graph viewer all run locally — the SQLite database lives in a .codegraph/ folder in your project, and the browser UI only binds to 127.0.0.1. Only anonymous, code-free usage telemetry (which you can disable) leaves the machine.

Do I need to keep re-running CodeGraph manually as I edit code?

No. After codegraph init, a background file watcher automatically re-indexes changed files (with a short debounce), and the MCP server reconciles any edits made while it was disconnected the moment it reconnects.

How many programming languages does CodeGraph support?

30, with identical full structural extraction and cross-file resolution for each — including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Scala, and more.

Will CodeGraph actually make my AI agent faster, or is that just a marketing number?

Independent 2026 benchmarking across seven real open-source codebases found consistent gains — 88% fewer tool calls and 53% faster answers on average — though the size of the win varies by repo (near-even on simpler questions, up to 78% cheaper on ones that would otherwise need 30+ exploratory tool calls). The one documented tradeoff is that CodeGraph's dense responses hold more tokens resident in context at once, which matters in long sessions on small context windows.

Is CodeGraph worth using on a small project?

The benchmarks show the smallest gains on repos or questions that only need a handful of tool calls anyway (Gin came out roughly cost-neutral). It pays off most on medium-to-large codebases where an agent would otherwise burn dozens of tool calls just locating relevant code before it can start answering.

Further reading: