@colbymchenry/codegraph
v0.7.3
Published
Supercharge Claude Code with semantic code intelligence. 94% fewer tool calls • 77% faster exploration • 100% local.
Maintainers
colbymchenryReadme
CodeGraph
Supercharge Claude Code with Semantic Code Intelligence
94% fewer tool calls · 77% faster exploration · 100% local
Get Started
npx @colbymchenry/codegraphInteractive installer configures Claude Code automatically
Why CodeGraph?
When Claude Code explores a codebase, it spawns Explore agents that scan files with grep, glob, and Read — consuming tokens on every tool call.
CodeGraph gives those agents a pre-indexed knowledge graph — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files.
Benchmark Results
Tested across 6 real-world codebases comparing Claude Code's Explore agent with and without CodeGraph:
Average: 92% fewer tool calls · 71% faster
| Codebase | With CG | Without CG | Improvement | |----------|---------|------------|-------------| | VS Code · TypeScript | 3 calls, 17s | 52 calls, 1m 37s | 94% fewer · 82% faster | | Excalidraw · TypeScript | 3 calls, 29s | 47 calls, 1m 45s | 94% fewer · 72% faster | | Claude Code · Python + Rust | 3 calls, 39s | 40 calls, 1m 8s | 93% fewer · 43% faster | | Claude Code · Java | 1 call, 19s | 26 calls, 1m 22s | 96% fewer · 77% faster | | Alamofire · Swift | 3 calls, 22s | 32 calls, 1m 39s | 91% fewer · 78% faster | | Swift Compiler · Swift/C++ | 6 calls, 35s | 37 calls, 2m 8s | 84% fewer · 73% faster |
All tests used Claude Opus 4.6 (1M context) with Claude Code v2.1.91. Each test spawned a single Explore agent with the same question.
Queries used: | Codebase | Query | |----------|-------| | VS Code | "How does the extension host communicate with the main process?" | | Excalidraw | "How does collaborative editing and real-time sync work?" | | Claude Code (Python+Rust) | "How does tool execution work end to end?" | | Claude Code (Java) | "How does tool execution work end to end?" | | Alamofire | "Trace how a request flows from Session.request() through to the URLSession layer" | | Swift Compiler | "How does the Swift compiler handle error diagnostics?" |
With CodeGraph — the agent uses codegraph_explore and stops:
| Codebase | Files Indexed | Nodes | Tool Uses | Tokens | Time | File Reads |
|----------|--------------|-------|-----------|--------|------|------------|
| VS Code (TypeScript) | 4,002 | 59,377 | 3 | 56.6k | 17s | 0 |
| Excalidraw (TypeScript) | 626 | 9,859 | 3 | 57.1k | 29s | 0 |
| Claude Code (Python+Rust) | 115 | 3,080 | 3 | 67.1k | 39s | 0 |
| Claude Code (Java) | — | — | 1 | 40.8k | 19s | 0 |
| Alamofire (Swift) | 102 | 2,624 | 3 | 57.3k | 22s | 0 |
| Swift Compiler (Swift/C++) | 25,874 | 272,898 | 6 | 77.4k | 35s | 0 |
Without CodeGraph — the agent uses grep, find, ls, and Read extensively: | Codebase | Tool Uses | Tokens | Time | File Reads | |----------|-----------|--------|------|------------| | VS Code (TypeScript) | 52 | 89.4k | 1m 37s | ~15 | | Excalidraw (TypeScript) | 47 | 77.9k | 1m 45s | ~20 | | Claude Code (Python+Rust) | 40 | 69.3k | 1m 8s | ~15 | | Claude Code (Java) | 26 | 73.3k | 1m 22s | ~15 | | Alamofire (Swift) | 32 | 52.4k | 1m 39s | ~10 | | Swift Compiler (Swift/C++) | 37 | 99.1k | 2m 8s | ~20 |
Key observations:
- With CodeGraph, the agent never fell back to reading files — it trusted the codegraph_explore results completely
- Without CodeGraph, agents spent most of their time on discovery (find, ls, grep) before they could even start reading relevant code
- The Java codebase needed only 1 codegraph_explore call to answer the entire question
- Cross-language queries (Python+Rust) worked seamlessly — CodeGraph's graph traversal found connections across language boundaries
- The Swift benchmark (Alamofire) traced a 9-step call chain from
Session.request()toURLSession.dataTask()— CodeGraph's graph traversal at depth 3 captured the full chain in one explore call - The Swift Compiler benchmark is the largest codebase tested (25,874 files, 272,898 nodes) — CodeGraph indexed it in under 4 minutes and the agent answered a complex cross-cutting question with 6 explore calls and zero file reads in 35 seconds
Key Features
| | | |---|---| | Smart Context Building | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents | | Full-Text Search | Find code by name instantly across your entire codebase, powered by FTS5 | | Impact Analysis | Trace callers, callees, and the full impact radius of any symbol before making changes | | Always Fresh | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config | | 19+ Languages | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi | | 100% Local | No data leaves your machine. No API keys. No external services. SQLite database only |
Quick Start
1. Run the Installer
npx @colbymchenry/codegraphThe installer will:
- Prompt to install
codegraphglobally (needed for the MCP server) - Configure the MCP server in
~/.claude.json - Set up auto-allow permissions for CodeGraph tools
- Add global instructions to
~/.claude/CLAUDE.md - Optionally initialize your current project
2. Restart Claude Code
Restart Claude Code for the MCP server to load.
3. Initialize Projects
cd your-project
codegraph init -iThat's it! Claude Code will use CodeGraph tools automatically when a .codegraph/ directory exists.
Install globally:
npm install -g @colbymchenry/codegraphAdd to ~/.claude.json:
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}Add to ~/.claude/settings.json (optional, for auto-allow):
{
"permissions": {
"allow": [
"mcp__codegraph__codegraph_search",
"mcp__codegraph__codegraph_context",
"mcp__codegraph__codegraph_callers",
"mcp__codegraph__codegraph_callees",
"mcp__codegraph__codegraph_impact",
"mcp__codegraph__codegraph_node",
"mcp__codegraph__codegraph_status",
"mcp__codegraph__codegraph_files"
]
}
}The installer automatically adds these instructions to ~/.claude/CLAUDE.md:
## CodeGraph
CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.
### If `.codegraph/` exists in the project
**NEVER call `codegraph_explore` or `codegraph_context` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").
**When spawning Explore agents**, include this instruction in the prompt:
> This project has CodeGraph initialized (.codegraph/ exists). Use `codegraph_explore` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
>
> **Rules:**
> 1. Follow the explore call budget in the `codegraph_explore` tool description — it scales automatically based on project size.
> 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative.
> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results.
**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):
| Tool | Use For |
|------|---------|
| `codegraph_search` | Find symbols by name |
| `codegraph_callers` / `codegraph_callees` | Trace call flow |
| `codegraph_impact` | Check what's affected before editing |
| `codegraph_node` | Get a single symbol's details |
### If `.codegraph/` does NOT exist
At the start of a session, ask the user if they'd like to initialize CodeGraph:
"I notice this project doesn't have CodeGraph initialized. Would you like me to run `codegraph init -i` to build a code knowledge graph?"How It Works
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ "Implement user authentication" │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Explore Agent │ ──── │ Explore Agent │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
└───────────┼────────────────────────┼─────────────────────────────┘
│ │
▼ ▼
┌───────────────────────────────────────────────────────────────────┐
│ CodeGraph MCP Server │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Search │ │ Callers │ │ Context │ │
│ │ "auth" │ │ "login()" │ │ for task │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ SQLite Graph DB │ │
│ │ • 387 symbols │ │
│ │ • 1,204 edges │ │
│ │ • Instant lookups │ │
│ └───────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).
Storage — Everything goes into a local SQLite database (
.codegraph/codegraph.db) with FTS5 full-text search.Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.
Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed.
CLI Reference
codegraph # Run interactive installer
codegraph install # Run installer (explicit)
codegraph init [path] # Initialize in a project (--index to also index)
codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt)
codegraph index [path] # Full index (--force to re-index, --quiet for less output)
codegraph sync [path] # Incremental update
codegraph status [path] # Show statistics
codegraph query <search> # Search symbols (--kind, --limit, --json)
codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json)
codegraph context <task> # Build context for AI (--format, --max-nodes)
codegraph affected [files...] # Find test files affected by changes (see below)
codegraph serve --mcp # Start MCP servercodegraph affected
Traces import dependencies transitively to find which test files are affected by changed source files.
codegraph affected src/utils.ts src/api.ts # Pass files as arguments
git diff --name-only | codegraph affected --stdin # Pipe from git diff
codegraph affected src/auth.ts --filter "e2e/*" # Custom test file pattern| Option | Description | Default |
|--------|-------------|---------|
| --stdin | Read file list from stdin | false |
| -d, --depth <n> | Max dependency traversal depth | 5 |
| -f, --filter <glob> | Custom glob to identify test files | auto-detect |
| -j, --json | Output as JSON | false |
| -q, --quiet | Output file paths only | false |
CI/hook example:
#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fiMCP Tools
When running as an MCP server, CodeGraph exposes these tools to Claude Code:
| Tool | Purpose |
|------|---------|
| codegraph_search | Find symbols by name across the codebase |
| codegraph_context | Build relevant code context for a task |
| codegraph_callers | Find what calls a function |
| codegraph_callees | Find what a function calls |
| codegraph_impact | Analyze what code is affected by changing a symbol |
| codegraph_node | Get details about a specific symbol (optionally with source code) |
| codegraph_files | Get indexed file structure (faster than filesystem scanning) |
| codegraph_status | Check index health and statistics |
Library Usage
import CodeGraph from '@colbymchenry/codegraph';
const cg = await CodeGraph.init('/path/to/project');
// Or: const cg = await CodeGraph.open('/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, format: 'markdown' });
const impact = cg.getImpactRadius(results[0].node.id, 2);
cg.watch(); // auto-sync on file changes
cg.unwatch(); // stop watching
cg.close();Configuration
The .codegraph/config.json file controls indexing:
{
"version": 1,
"languages": ["typescript", "javascript"],
"exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
"frameworks": [],
"maxFileSize": 1048576,
"extractDocstrings": true,
"trackCallSites": true
}| Option | Description | Default |
|--------|-------------|---------|
| languages | Languages to index (auto-detected if empty) | [] |
| exclude | Glob patterns to ignore | ["node_modules/**", ...] |
| frameworks | Framework hints for better resolution | [] |
| maxFileSize | Skip files larger than this (bytes) | 1048576 (1MB) |
| extractDocstrings | Extract docstrings from code | true |
| trackCallSites | Track call site locations | true |
Supported Languages
| Language | Extension | Status |
|----------|-----------|--------|
| TypeScript | .ts, .tsx | Full support |
| JavaScript | .js, .jsx, .mjs | Full support |
| Python | .py | Full support |
| Go | .go | Full support |
| Rust | .rs | Full support |
| Java | .java | Full support |
| C# | .cs | Full support |
| PHP | .php | Full support |
| Ruby | .rb | Full support |
| C | .c, .h | Full support |
| C++ | .cpp, .hpp, .cc | Full support |
| Swift | .swift | Full support |
| Kotlin | .kt, .kts | Full support |
| Dart | .dart | Full support |
| Svelte | .svelte | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
| Liquid | .liquid | Full support |
| Pascal / Delphi | .pas, .dpr, .dpk, .lpr | Full support (classes, records, interfaces, enums, DFM/FMX form files) |
Troubleshooting
"CodeGraph not initialized" — Run codegraph init in your project directory first.
Indexing is slow — Check that node_modules and other large directories are excluded. Use --quiet to reduce output overhead.
MCP server not connecting — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that codegraph serve --mcp works from the command line.
Missing symbols — The MCP server auto-syncs on save (wait a couple seconds). Run codegraph sync manually if needed. Check that the file's language is supported and isn't excluded by config patterns.
License
MIT
Made for the Claude Code community