codegraph/README.md

CodeGraph

Supercharge Claude Code, Cursor & Codex with Semantic Code Intelligence

94% fewer tool calls · 77% faster exploration · 100% local

Get Started

npx @colbymchenry/codegraph

_{Interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode}

Initialize Projects

cd your-project
codegraph init -i

---

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

Full benchmark details

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() to URLSession.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
Framework-aware Routes	Recognizes web-framework routing files and links URL patterns to their handlers across 13 frameworks
100% Local	No data leaves your machine. No API keys. No external services. SQLite database only

---

Framework-aware Routes

CodeGraph detects web-framework routing files and emits route nodes linked by references edges to their handler classes or functions. Querying callers of a view/controller now surfaces the URL pattern that binds it.

Framework	Shapes recognized
Django	path(), re_path(), url(), include() in urls.py (CBV .as_view(), dotted paths)
Flask	@app.route('/path', methods=[...]), blueprint routes
FastAPI	@app.get(...), @router.post(...), all standard methods
Express	app.get(...), router.post(...) with middleware chains
Laravel	Route::get(), Route::resource(), Controller@action, tuple syntax
Rails	get '/x', to: 'users#index', hash-rocket => syntax
Spring	@GetMapping, @PostMapping, @RequestMapping on methods
Gin / chi / gorilla / mux	r.GET(...), router.HandleFunc(...)
Axum / actix / Rocket	.route("/x", get(handler))
ASP.NET	[HttpGet("/x")] attributes on action methods
Vapor	app.get("x", use: handler)
React Router / SvelteKit	Route component nodes

---

Quick Start

1. Run the Installer

npx @colbymchenry/codegraph

The installer will:

• Ask which agent(s) to configure — auto-detects installed ones from: Claude Code, Cursor, Codex CLI, opencode
• Prompt to install codegraph on your PATH (so agents can launch the MCP server)
• Ask whether configs apply to all your projects or just this one
• Write each chosen agent's MCP server config + an instructions file (e.g. CLAUDE.md, .cursor/rules/codegraph.mdc, ~/.codex/AGENTS.md)
• Set up auto-allow permissions when Claude Code is one of the targets
• Initialize your current project (local installs only)

Non-interactive (scripting / CI):

codegraph install --yes                              # auto-detect agents, install global
codegraph install --target=cursor,claude --yes       # explicit target list
codegraph install --target=auto --location=local     # detected agents, project-local
codegraph install --print-config codex               # print snippet, no file writes

Flag	Values	Default
--target	auto, all, none, or csv (claude,cursor,...)	prompt
--location	global, local	prompt
--yes	(boolean)	prompt every step
--no-permissions	(boolean) skip Claude auto-allow list	permissions on
--print-config <id>	dump snippet for one agent and exit	—

2. Restart Your Agent

Restart your agent (Claude Code / Cursor / Codex CLI / opencode) for the MCP server to load.

3. Initialize Projects

cd your-project
codegraph init -i

Builds the per-project knowledge graph index. Also wires up any project-local agent surfaces (e.g. Cursor's .cursor/rules/codegraph.mdc) so a single global codegraph install works in every project you open — no need to re-run the installer per project.

That's it — your agent will use CodeGraph tools automatically when a .codegraph/ directory exists.

Manual Setup (Alternative)

Install globally:

npm install -g @colbymchenry/codegraph

Add 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"
    ]
  }
}

Global Instructions Reference

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   │                            │
│              └───────────────────────┘                            │
└───────────────────────────────────────────────────────────────────┘

1. Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements).

2. Storage — Everything goes into a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search.

3. Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns.

4. 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 server

codegraph 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
fi

---

MCP 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
Scala	.scala, .sc	Full support (classes, traits, methods, type aliases, Scala 3 enums)
Dart	.dart	Full support
Svelte	.svelte	Full support (script extraction, Svelte 5 runes, SvelteKit routes)
Vue	.vue	Full support (script + script-setup extraction, Nuxt page/API/middleware 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.

Indexing is slow / MCP database is locked / WASM fallback active — codegraph ships with a WASM SQLite fallback for environments where better-sqlite3 (a native module, declared as optionalDependencies) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit database is locked while indexing runs. Run codegraph status and look at the Backend: line:

• Backend: native — you're on the fast path, nothing to do.

• Backend: wasm — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:

  # macOS
  xcode-select --install                                  # installs the C compiler
  
  # Linux (Debian / Ubuntu)
  sudo apt install build-essential python3 make
  
  # Linux (RHEL / Fedora)
  sudo yum groupinstall "Development Tools"
  
  # Then rebuild on any platform:
  npm rebuild better-sqlite3
  
  # Or force-include as a hard dep:
  npm install better-sqlite3 --save
  

  After the fix, codegraph status should show Backend: native.

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

Report Bug · Request Feature