Colby McHenry
789158bfd4
Updates Swift and Kotlin language support from basic to full in documentation and reduces explore budget thresholds to optimize performance for smaller codebases.
426 lines
18 KiB
Markdown
426 lines
18 KiB
Markdown
<div align="center">
|
|
|
|
# CodeGraph
|
|
|
|
### Supercharge Claude Code with Semantic Code Intelligence
|
|
|
|
**94% fewer tool calls · 77% faster exploration · 100% local**
|
|
|
|
[](https://www.npmjs.com/package/@colbymchenry/codegraph)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://nodejs.org/)
|
|
|
|
[](#)
|
|
[](#)
|
|
[](#)
|
|
|
|
<br />
|
|
|
|
### Get Started
|
|
|
|
```bash
|
|
npx @colbymchenry/codegraph
|
|
```
|
|
|
|
<sub>Interactive installer configures Claude Code automatically</sub>
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 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** |
|
|
|
|
<details>
|
|
<summary><strong>Full benchmark details</strong></summary>
|
|
|
|
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
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```bash
|
|
npx @colbymchenry/codegraph
|
|
```
|
|
|
|
The installer will:
|
|
- Prompt to install `codegraph` globally (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
|
|
|
|
```bash
|
|
cd your-project
|
|
codegraph init -i
|
|
```
|
|
|
|
That's it! Claude Code will use CodeGraph tools automatically when a `.codegraph/` directory exists.
|
|
|
|
<details>
|
|
<summary><strong>Manual Setup (Alternative)</strong></summary>
|
|
|
|
**Install globally:**
|
|
```bash
|
|
npm install -g @colbymchenry/codegraph
|
|
```
|
|
|
|
**Add to `~/.claude.json`:**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"codegraph": {
|
|
"type": "stdio",
|
|
"command": "codegraph",
|
|
"args": ["serve", "--mcp"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Add to `~/.claude/settings.json` (optional, for auto-allow):**
|
|
```json
|
|
{
|
|
"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"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Global Instructions Reference</strong></summary>
|
|
|
|
The installer automatically adds these instructions to `~/.claude/CLAUDE.md`:
|
|
|
|
```markdown
|
|
## 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?"
|
|
```
|
|
|
|
</details>
|
|
|
|
---
|
|
|
|
## 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](https://tree-sitter.github.io/) 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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
#!/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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Made for the Claude Code community**
|
|
|
|
[Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)
|
|
|
|
</div>
|