Introduction #
"~35% cheaper · ~70% fewer tool calls · 100% local"
This is the No.71 article in the "One Open Source Project a Day" series. Today we are exploring CodeGraph.
Start with a scenario: you ask Claude Code "How is AuthService being called?" Without any assistance, Claude's approach is: glob-scan directories, run multiple greps, read several files — then finally answer. The whole process might trigger 10–15 tool calls and consume hundreds of thousands of tokens.
CodeGraph's insight is tofront-load this work: before you start, it has already parsed your codebase with tree-sitter into a semantic graph stored in a local SQLite database, then exposes 8 query tools to AI agents via MCP. When the agent needs to understand code, a single codegraph_context
call returns entry points, related symbols, and code snippets —no file reading required.
9.6k Stars, 588 Forks. Benchmarks across 7 real open-source projects: average 35% cost savings, 70% fewer tool calls, 49% speed improvement. On VS Code's large TypeScript repository, one architecture Q&A dropped from 1.4M tokens to 393k — cost from $0.64 to $0.42.
What You Will Learn
- CodeGraph's four-stage pipeline: Extract → Store → Resolve → Auto-Sync
- The 8 MCP tools and when to use each
- A detailed breakdown of benchmark results across 7 projects: why do larger codebases benefit more?
- How 19-language support and 13-framework route recognition work
- Complete setup walkthrough from installation to Claude Code integration
codegraph affected
: using dependency tracing for smart CI test selection
Prerequisites
- Familiarity with Claude Code, Cursor, or similar AI coding tools
- Basic understanding of MCP (Model Context Protocol)
- Node.js experience
Project Background #
Project Introduction
CodeGraph is alocal semantic code knowledge graph tool designed specifically to improve AI coding agent efficiency. Its core insight:
AI agents spend a massive amount of tokens and time in the "discovery phase" — scanning directories, searching for symbols, reading files — rather than on the actual reasoning and generation.
CodeGraph's solution is tooutsource the discovery phase to a pre-built index: before you start working, the index is already ready, letting AI agents pull structured code knowledge directly instead of exploring the file system from scratch.
The technology choices are pragmatic: tree-sitter for AST parsing (mature, multi-language, high-performance), SQLite FTS5 for full-text search (zero external dependencies, fully local), and native OS file events for live sync (FSEvents/inotify/ReadDirectoryChangesW).
Author/Team
-Author: Colby McHenry (GitHub: colbymchenry) -** Repository**:colbymchenry/codegraph -** Distribution**: npm package@colbymchenry/codegraph
Project Stats
-
⭐ GitHub Stars:9,600+- 🍴 Forks:** 588**- 📦 npm package:
@colbymchenry/codegraph -
🔧 Runtime: Node.js 20–24
-
💻 Platforms: Windows, macOS, Linux
-
📄 License: MIT
-
🌐 Repository: colbymchenry/codegraph
Main Features #
Core Utility
CodeGraph inserts a pre-built index layer between AI agents and codebases:
Codebase (TypeScript / Python / Go / ...)
↓ tree-sitter parsing
Semantic graph (symbols + relationships + call chains)
↓ stored in SQLite FTS5
Local knowledge base
↓ exposed via MCP
AI coding agents (Claude Code / Cursor / Codex CLI / OpenCode)
User: "How is AuthService being called?"
→ Agent: glob("src/**/*.ts") # Tool call 1
→ Agent: grep("AuthService") # Tool call 2
→ Agent: read("auth.service.ts") # Tool call 3
→ Agent: grep("import.*Auth") # Tool call 4
→ Agent: read("user.controller.ts") # Tool call 5
→ Agent: read("app.module.ts") # Tool call 6
... 10–15 total tool calls, massive token consumption
With CodeGraph:
User: "How is AuthService being called?"
→ Agent: codegraph_callers("AuthService") # Tool call 1
→ Returns: full caller list + call sites + code snippets
→ Agent answers directly, no file reading needed
Quick StartOne-command install (recommended):
npx @colbymchenry/codegraph
cd your-project
codegraph init -i
codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local
npm install -g @colbymchenry/codegraph
Add to ~/.claude.json
(or project-level .claude.json
):
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
codegraph status # Check index status and stats
codegraph query "UserService" # Test symbol search
The 8 MCP Tools
The complete toolset CodeGraph exposes to AI agents:
| Tool | Purpose | Typical Invocation |
|---|---|---|
codegraph_search |
||
| Find symbols by name | "Find all functions called authenticate" | |
codegraph_context |
||
| Build code context for a task | "What code is relevant to the login flow?" | |
codegraph_callers |
||
| Find what calls a function | "What calls AuthService?" | |
codegraph_callees |
||
| Find what a function calls | "What does processPayment call internally?" | |
codegraph_impact |
||
| Analyze change impact radius | "What breaks if I change this function?" | |
codegraph_node |
||
| Get details about a specific symbol | "Show me UserController's full signature" | |
codegraph_files |
||
| Get indexed file structure | "What is the overall project structure?" | |
codegraph_status |
||
| Check index health and stats | "How many symbols are indexed? Last sync?" | codegraph_context is the most important tool — it doesn't just return search results; it intelligently assembles a comprehensive context package for a given task, including entry points, related symbols, and code snippets: |
codegraph context "fix user login bug"
Project Advantages
| Dimension | CodeGraph | Native AI Agent (no assist) | Other code indexers |
|---|---|---|---|
| Tool call count | |||
| ~70% fewer | High (re-scans each task) | Partial reduction | |
| Token usage | |||
| ~59% fewer | High | Partial reduction | |
| Data privacy | |||
| 100% local | Depends on agent | Most require uploads | |
| Real-time sync | |||
| Native OS file events | N/A | Usually polling or manual | |
| Language support | |||
| 19+ languages | Depends on agent | Usually 3–5 | |
| Framework route detection | |||
| 13 frameworks | None | Rare | |
| Installation complexity | |||
| One npx command | N/A | Usually requires server |
Detailed Analysis #
1. The Four-Stage PipelineStage 1: Extraction tree-sitter parses source files into ASTs, extracting:
-Symbols: functions, classes, methods, interfaces, variable definitions -** Relationships**: function calls, module imports, class inheritance, interface implementations
tree-sitter's key advantage: it is afault-tolerant parser— it can extract partial structure even when code has syntax errors. This is critical for indexing files that are actively being edited.Stage 2: Storage All data lands in a local SQLite database using the FTS5 (Full-Text Search 5) extension:
-- Symbols table (simplified)
CREATE VIRTUAL TABLE symbols USING fts5(
name, -- Symbol name
kind, -- function/class/method/...
file_path, -- Source file
line_start, -- Starting line
signature, -- Function signature
docstring, -- Documentation comment
code_snippet -- Code excerpt
);
-- Relationships table
CREATE TABLE edges (
from_id INTEGER, -- Caller symbol ID
to_id INTEGER, -- Callee symbol ID
kind TEXT, -- calls/imports/inherits/implements
file TEXT,
line INTEGER
);
js
Source code: import { AuthService } from './auth.service'
...
this.authService.login(user)
↓ resolution
Graph edges: UserController.login → AuthService.login (calls)
UserController → AuthService (imports)
```**Stage 4: Auto-Sync** Uses native OS file events (not polling!) to detect changes:
- macOS:
`FSEvents`
- Linux:
`inotify`
- Windows:
`ReadDirectoryChangesW`
A**2-second debounce** prevents triggering mass rebuilds when files change rapidly — it waits for changes to settle before doing incremental updates.
### 2. Benchmark Deep Dive
Test conditions: Claude Code (headless, Opus 4.7) answering architecture questions. Each result is the median of 4 runs on the same question, across 7 real open-source repositories.
Project Language Size Cost ↓ Token ↓ Speed ↑ Tool Calls ↓ ────────────────────────────────────────────────────────────────────────────────────── VS Code TypeScript ~10k files 35% 73% 41% 72% Excalidraw TypeScript ~600 files 47% 73% 60% 86% Django Python ~2.7k files 34% 64% 59% 81% Tokio Rust ~700 files 52% 81% 63% 89% OkHttp Java ~640 files 17% 41% 36% 64% Gin Go ~150 files 22% 23% 34% 19% Alamofire Swift ~100 files 38% 59% 51% 77% ────────────────────────────────────────────────────────────────────────────────────── Average 35% 59% 49% 70%
### 3. 19 Languages + 13 Framework Route Detection**Language support**(via tree-sitter grammars):
TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Scala**Framework route detection** is a differentiating feature — CodeGraph doesn't just recognize symbols, it understands the mapping between URL routes and their handler functions:
urlpatterns = [ path('users/int:pk/', UserDetailView.as_view()), ]
@app.get("/items/{item_id}") async def read_item(item_id: int): ...
The 13 supported frameworks: Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin/chi/gorilla/mux, Axum/actix/Rocket, ASP.NET, Vapor, React Router/SvelteKit.
This means AI agents can ask "Where is the handler for `/api/users/:id`
?" and get a precise answer, without needing to scan routing config files.
### 4. `codegraph affected`
— Smart CI Test Selection
An underappreciated feature: by tracing import dependencies, it identifies which test files are actually affected by changed source files.