CodeGraph: Helping AI Coding Assistants Understand the Codebase

1. What CodeGraph Is

CodeGraph is a local-first code intelligence tool. It parses a codebase with tree-sitter, stores symbols, relationships, and files in a local SQLite database, and exposes them as a queryable knowledge graph through MCP, a CLI, and a TypeScript API.

Put simply, it turns “grep, glob, and Read all over the code” into an index built ahead of time, so an AI assistant can answer structural questions with just a few queries.

The project has been published to npm as @colbymchenry/codegraph, and supports mainstream AI coding tools including Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, and Gemini CLI.

Project repository: https://github.com/colbymchenry/codegraph
Official documentation: https://colbymchenry.github.io/codegraph/

2. Why You Need It

When an AI coding assistant explores an unfamiliar codebase, most of its time goes into discovery: find the files first, then read them, then piece together the call relationships. That process generates a large number of grep / glob / Read calls, burns tokens, and slows down responses.

CodeGraph’s approach is this: the structure is already built before the agent asks. Symbol relationships, call graphs, inheritance chains, route bindings, and the like all live in the index, and queries run at sub-millisecond speed.

Without CodeGraph, the agent has to “sweep the files” itself; with CodeGraph, the agent goes straight to “querying the graph.”

3. Comparison: With and Without CodeGraph

3.1 The Same Question, Two Paths

Suppose you ask the agent: “How does a request reach the database?”

Without CodeGraph:

Question → grep for keywords → glob for directories → Read multiple files
     → grep again for call relationships → Read again → maybe spawn a sub-agent to keep sweeping
     → piece together an answer (10–20+ tool calls, a large number of tokens)

With CodeGraph:

Question → codegraph_explore (returns the relevant symbol source + call path in one go)
     → codegraph_node to dig deeper if needed (1–4 calls in total, usually 0 Reads)
     → give the answer

Dimension	Without CodeGraph	With CodeGraph
Finding a symbol definition	grep text, prone to missing duplicates and false matches	FTS5 symbol search, with type, location, signature
Call relationships	Multiple greps + Reads to trace by hand	callers / callees / explore paths unfolded in one step
Impact analysis	Nearly impossible to do systematically	impact computes the blast radius of a change
Cross-file flows	Breaks easily at language/module boundaries	Framework routes + dynamic dispatch bridged by synthesized edges
Large files	Read the whole file, token explosion	Returns only the relevant symbol fragments
Data privacy	No extra dependencies	100% local SQLite, never leaves the machine
First-time cost	Zero	Requires `codegraph init` to build the index (one-time)

3.2 Quantitative Benchmarks

Test method: Claude Code in headless mode, the same architectural question, with and without the CodeGraph MCP, 4 runs each taking the median. Covers 7 open-source repositories and 7 languages, ranging in size from ~110 files to ~10k files.

Summary (median average):

Metric	Improvement
Cost	About 16% lower
Tokens	About 47% fewer
Time	About 22% faster
Tool calls	About 58% fewer
File reads	Close to 0 (4–9 per question without CodeGraph)

Per-repository comparison:

Codebase	Language · Size	Cost	Tokens	Time	Tool calls
VS Code	TS · ~10k	↓18%	↓64%	↓11%	↓81%
Excalidraw	TS · ~640	Flat	↓25%	↓27%	↓40%
Django	Python · ~3k	↓8%	↓60%	↓13%	↓77%
Tokio	Rust · ~790	Flat	↓38%	↓18%	↓57%
OkHttp	Java · ~645	↓25%	↓54%	↓31%	↓50%
Gin	Go · ~110	↓19%	↓23%	↓24%	↓44%
Alamofire	Swift · ~110	↓40%	↓64%	↓33%	↓58%

The pattern is obvious: the larger the repository and the more complex the structural question, the more exaggerated the discovery overhead becomes without CodeGraph.

3.3 When You Can Skip It

Scenario	Explanation
Tiny projects (a few files)	The agent reading everything directly is faster than building an index
Plain-text search	Finding log strings, comments, config entries — grep is a better fit
Non-source files	README, `.env`, `yaml` config — CodeGraph does not index them
Compilation/type correctness	Still relies on the compiler, linter, and tests
Fully dynamic reflection	Runtime eval and heavy reflection — the graph will mark what it does not cover
The agent does not use the CodeGraph tools	Installed but the agent still takes the grep path, which becomes pure overhead

4. How It Works

CodeGraph turns source code into a queryable graph in four stages:

File → Extract (tree-sitter AST) → Store (SQLite + FTS5)
              ↓
        Resolve (imports, name matching, framework patterns)
              ↓
        Graph query (callers, callees, impact)
              ↓
        Context building (AI-facing markdown/JSON)

4.1 Extraction

tree-sitter parses source into an AST, and per-language extractors pull out of it:

Nodes: functions, classes, methods, types, routes, components, etc.
Edges: calls, imports, inheritance, implementation, references, etc.

Parsing runs in a separate worker thread. The extraction results come from the AST, not an LLM summary, so they are reproducible and trustworthy.

4.2 Storage

All data is written to .codegraph/codegraph.db under the project directory, with FTS5 full-text search support. It prefers the native better-sqlite3 and transparently falls back to the WASM backend when unavailable.

4.3 Resolution

After extraction, references still have to be connected to definitions:

Function calls → target definitions
import → source file
Class inheritance, interface implementation
Framework routes (Django urls.py, Express app.get, Spring @GetMapping, etc.)

For dynamic dispatch boundaries that static resolution cannot follow (callbacks, observers, React setState→render, JSX child components, etc.), CodeGraph bridges them with synthesized edges and marks them provenance: 'heuristic', so the agent knows how the edge was inferred.

4.4 Automatic Sync

Once the MCP service starts, it uses the operating system’s native file event watching to detect project changes and incrementally updates the index after debouncing. By default no manual sync is needed; the graph stays fresh as you code.

4.5 What the Graph Can Answer

Question type	Corresponding capability
Where is X defined?	Symbol search (FTS5)
Who calls Y?	callers traversal
What does Y call?	callees / node source
What does changing Z affect?	impact blast radius
How does X reach Y?	Call paths in explore
Which handler does this URL map to?	Framework route resolution

Node types include file, module, class, function, method, interface, route, component, and 20+ more; edge types include contains, calls, imports, extends, implements, references, returns, and so on.

5. Quick Start

5.1 Install the CLI

No Node.js required (a runtime is bundled):

1
2
3
4
5
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

With Node already installed you can also use:

1
npm i -g @colbymchenry/codegraph

After installing, open a new terminal to make sure the codegraph command is available.

5.2 Connect It to Your AI Tools

1
codegraph install

The installer automatically detects installed agents (Claude Code, Cursor, Codex, etc.) and writes the CodeGraph MCP service into the corresponding configuration. Installing only the CLI is not enough — this step is what actually connects CodeGraph to the agent.

Non-interactive install:

1
codegraph install --yes

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
┌  CodeGraph v1.0.1
│
◆  Claude Code: Updated ~/.claude.json
│
◆  Claude Code: Updated ~/.claude/settings.json
│
◆  Claude Code: Created ~/.claude/CLAUDE.md
│
◆  Cursor: Updated ~/.cursor/mcp.json
│
●  Cursor: Restart Cursor for MCP changes to take effect.
│
◆  Codex CLI: Updated ~/.codex/config.toml
│
◆  Codex CLI: Created ~/.codex/AGENTS.md
│
◇  Quick start ───────╮
│                     │
│  cd your-project    │
│  codegraph init -i  │
│                     │
├─────────────────────╯
codegraph collects anonymous usage stats (no code, paths, or names) — "codegraph telemetry off" or CODEGRAPH_TELEMETRY=0 disables. Details: https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md
│
└  Done! Restart your agents to use CodeGraph.

5.3 Initialize the Project

1
2
cd your-project
codegraph init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
┌  Initializing CodeGraph
│
◆  Initialized in /Users/shaowenchen/Code/github/your-project
│
│  ◆ Scanning files — 249 found
│  ◆ Parsing code — done
│  ◆ Resolving refs — done
│
◆  Indexed 249 files
│
●  4,076 nodes, 16,629 edges in 2.1s
│
└  Done

This creates .codegraph/ under the project and builds the full index. Afterward file changes sync automatically; no need to run init again.

5.4 Restart the Agent

Restart Cursor / Claude Code and so on so the MCP configuration takes effect. When a .codegraph/ directory exists in the project, the agent automatically gets the CodeGraph tools.

5.5 Uninstalling

1
2
codegraph uninstall          # remove the MCP configuration from all agents
codegraph uninit             # delete the .codegraph/ index for a single project

6. MCP Tool Reference

CodeGraph exposes the following tools over MCP:

Tool	Purpose
`codegraph_explore`	The workhorse: returns the source, call paths, and impact scope for several related symbols at once
`codegraph_search`	Find a symbol by name
`codegraph_callers`	Find all call sites (including callback registration)
`codegraph_callees`	Find what is being called
`codegraph_impact`	Analyze the blast radius of changing a symbol
`codegraph_node`	Get the details, full source, and call chain of a single symbol
`codegraph_files`	Inspect the structure of the indexed files
`codegraph_status`	Check the health of the index

Choosing a tool by intent:

“How does X work?” “How does X reach Y?” → codegraph_explore (usually enough in one call)
“Where is X?” → codegraph_search
“Who calls this function?” “What will break if I change it?” → codegraph_callers
“What does this function call internally?” → codegraph_node (includeCode: true)
Reading a source file → codegraph_node with a file path (equivalent to Read, plus dependency information)

7. Usage Advice

Use CodeGraph directly for structural questions; do not rebuild with grep + Read information the index already has
Trust the AST resolution results; there is no need to double-check with grep
Watch for staleness hints after editing — if a response begins with ⚠️ Some files referenced below were edited since the last index sync…, use Read to confirm the latest content of the listed files
For a project that is not indexed: CodeGraph will report inactive, and the user needs to run codegraph init themselves

A few design principles worth knowing:

Local-first: the index lives in SQLite under .codegraph/, no API Key required, no external service dependency
Determinism over guessing: the graph comes from the tree-sitter AST, and synthesized edges are explicitly marked as heuristic inferences
One call returns enough context: codegraph_explore is designed to give an answer in a single call
Framework-aware: route resolution for 17+ web frameworks (Django, Flask, FastAPI, Express, Spring, Gin, Rails, etc.)

8. Common CLI Commands

1
2
3
4
5
6
codegraph init          # initialize and build the index
codegraph status        # view index status and files pending sync
codegraph sync          # manual sync (usually unnecessary)
codegraph query ...     # command-line query
codegraph upgrade       # check for and apply upgrades
codegraph serve --mcp   # start the MCP service manually (the agent starts it automatically)

9. Summary

CodeGraph turns an AI coding assistant from “fishing for needles in an ocean of files” into “querying a pre-built code knowledge graph directly.”

Comparison: without CodeGraph the agent relies on grep/Read for discovery (10–20+ calls); with CodeGraph it is usually 1–4 queries and close to zero file reads
Principle: tree-sitter parsing → SQLite storage → reference resolution + framework awareness → exposed to the agent via MCP
Usage: install the CLI → codegraph install to connect the agent → codegraph init in the project → restart the agent

If you already write code with Cursor or Claude Code, spending two minutes on the installation flow will make the agent noticeably more efficient on structural questions.