🔮 CodeGraph

Supercharge Claude Code with Semantic Code Intelligence

30% fewer tokens • 25% fewer tool calls • 100% local

Get Started

npx @colbymchenry/codegraph

_{Interactive installer configures Claude Code automatically}

🚀 Why CodeGraph?

When you ask Claude Code to work on a complex task, it spawns Explore agents that scan your codebase using grep, glob, and file reads. These agents consume tokens with every tool call.

CodeGraph gives those agents a semantic knowledge graph — pre-indexed symbol relationships, call graphs, and code structure. Instead of scanning files, agents query the graph instantly.

📊 Benchmark Results

We ran the same complex task 3 times with and without CodeGraph:

Metric	Without CodeGraph	With CodeGraph	Improvement
Explore tokens	157.8k	111.7k	29% fewer
Per-agent tokens	74.0k	46.4k	37% fewer
Tool calls	60	45	25% fewer
Main context usage	28.7%	24.0%	4.7% less

Full benchmark data

With CodeGraph:

Test	Agents	Tool Uses	Explore Tokens	Plan Tokens	Time
1	3	54	149.7k	76.4k	1m 43s
2	2	41	102.1k	74.8k	1m 29s
3	2	40	83.3k	63.3k	1m 25s
Avg	2.3	45	111.7k	71.5k	1m 32s

Without CodeGraph:

Test	Agents	Tool Uses	Explore Tokens	Plan Tokens	Time
1	3	74	177.3k	80.5k	1m 54s
2	2	55	149.3k	64.0k	1m 27s
3	2	51	146.7k	62.3k	1m 17s
Avg	2.3	60	157.8k	68.9k	1m 33s

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

Without CodeGraph: Explore agents use grep, glob, and Read to scan files → many API calls, high token usage

With CodeGraph: Explore agents query the graph via MCP tools → instant results, local processing, fewer tokens

✨ Key Features

🧠 Smart Context Building One tool call returns everything Claude needs—entry points, related symbols, and code snippets. No more expensive exploration agents.	🔍 Semantic Search Find code by meaning, not just text. Search for "authentication" and find `login`, `validateToken`, `AuthService`—even with different naming conventions.	📈 Impact Analysis Know exactly what breaks before you change it. Trace callers, callees, and the full impact radius of any symbol.
🌍 15+ Languages TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin—all with the same API.	🔒 100% Local No data leaves your machine. No API keys. No external services. Everything runs on your local SQLite database.	⚡ Always Fresh Git hooks automatically sync the index on every commit. Your code intelligence is always up to date.

🎯 Quick Start

1. Run the Installer

npx @colbymchenry/codegraph

The interactive installer will:

Configure the MCP server in ~/.claude.json
Set up auto-allow permissions for CodeGraph tools
Add global instructions to ~/.claude/CLAUDE.md (teaches Claude how to use CodeGraph)
Optionally initialize your current project

2. Restart Claude Code

Restart Claude Code for the MCP server to load.

3. Initialize Projects

For each project you want to use CodeGraph with:

cd your-project
codegraph init -i

That's it! Claude Code will now use CodeGraph tools automatically when a .codegraph/ directory exists.

Manual Setup (Alternative)

If you prefer manual configuration:

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

Global Instructions Reference

The installer automatically adds these instructions to ~/.claude/CLAUDE.md. This is provided here for reference:

## CodeGraph

CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.

### If `.codegraph/` exists in the project

**Use codegraph tools for faster exploration.** These tools provide instant lookups via the code graph instead of scanning files:

| Tool | Use For |
|------|---------|
| `codegraph_search` | Find symbols by name (functions, classes, types) |
| `codegraph_context` | Get relevant code context for a task |
| `codegraph_callers` | Find what calls a function |
| `codegraph_callees` | Find what a function calls |
| `codegraph_impact` | See what's affected by changing a symbol |
| `codegraph_node` | Get details + source code for a symbol |

**When spawning Explore agents in a codegraph-enabled project:**

Tell the Explore agent to use codegraph tools for faster exploration.

**For quick lookups in the main session:**
- Use `codegraph_search` instead of grep for finding symbols
- Use `codegraph_callers`/`codegraph_callees` to trace code flow
- Use `codegraph_impact` before making changes to see what's affected

### 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?"

📋 Requirements

Node.js >= 18.0.0

💻 CLI Usage

codegraph                   # Run interactive installer
codegraph install           # Run interactive installer (explicit)
codegraph init [path]       # Initialize in a project
codegraph index [path]      # Full index
codegraph sync [path]       # Incremental update
codegraph status [path]     # Show statistics
codegraph query <search>    # Search symbols
codegraph context <task>    # Build context for AI
codegraph hooks install     # Install git auto-sync hook
codegraph serve --mcp       # Start MCP server

📖 CLI Commands

`codegraph` / `codegraph install`

Run the interactive installer for Claude Code integration. Configures MCP server and permissions automatically.

codegraph                         # Run installer (when no args)
codegraph install                 # Run installer (explicit)
npx @colbymchenry/codegraph       # Run via npx (no global install needed)

The installer will:

Ask for installation location (global ~/.claude or local ./.claude)
Configure the MCP server in claude.json
Optionally set up auto-allow permissions
Add global instructions to ~/.claude/CLAUDE.md (teaches Claude how to use CodeGraph)
For local installs: initialize and index the current project

`codegraph init [path]`

Initialize CodeGraph in a project directory. Creates a .codegraph/ directory with the database and configuration.

codegraph init                    # Initialize in current directory
codegraph init /path/to/project   # Initialize in specific directory
codegraph init --index            # Initialize and immediately index
codegraph init --no-hooks         # Skip git hook installation

`codegraph index [path]`

Index all files in the project. Extracts functions, classes, methods, and their relationships.

codegraph index                   # Index current directory
codegraph index --force           # Force full re-index
codegraph index --quiet           # Suppress progress output

`codegraph sync [path]`

Incrementally sync changes since the last index. Only processes added, modified, or removed files.

codegraph sync                    # Sync current directory
codegraph sync --quiet            # Suppress output

`codegraph status [path]`

Show index status and statistics.

codegraph status

Output includes:

Files indexed, nodes, edges
Nodes by kind (functions, classes, methods, etc.)
Files by language
Pending changes (if any)
Git hook status

`codegraph query <search>`

Search for symbols in the codebase by name.

codegraph query "authenticate"           # Search for symbols
codegraph query "User" --kind class      # Filter by kind
codegraph query "process" --limit 20     # Limit results
codegraph query "validate" --json        # Output as JSON

`codegraph context <task>`

Build relevant code context for a task. Uses semantic search to find entry points, then expands through the graph to find related code.

codegraph context "fix checkout bug"
codegraph context "add user authentication" --format json
codegraph context "refactor payment service" --max-nodes 30

`codegraph hooks`

Manage git hooks for automatic syncing.

codegraph hooks install    # Install post-commit hook
codegraph hooks remove     # Remove hook
codegraph hooks status     # Check if hook is installed

`codegraph serve`

Start CodeGraph as an MCP server for AI assistants.

codegraph serve                          # Show MCP configuration help
codegraph serve --mcp                    # Start MCP server (stdio)
codegraph serve --mcp --path /project    # Specify project path

🔌 MCP Tools Reference

When running as an MCP server, CodeGraph exposes these tools to AI assistants. These tools are designed to be used by Claude's Explore agents for faster, more efficient codebase exploration.

`codegraph_context`

Build context for a specific task. Good for focused queries.

codegraph_context(task: "fix checkout validation bug", maxNodes: 20)

`codegraph_search`

Quick symbol search by name. Returns locations only.

codegraph_search(query: "UserService", kind: "class", limit: 10)

`codegraph_callers` / `codegraph_callees`

Find what calls a function, or what a function calls.

codegraph_callers(symbol: "validatePayment", limit: 20)
codegraph_callees(symbol: "processOrder", limit: 20)

`codegraph_impact`

Analyze what code would be affected by changing a symbol.

codegraph_impact(symbol: "UserService", depth: 2)

`codegraph_node`

Get details about a specific symbol. Use includeCode: true only when needed.

codegraph_node(symbol: "authenticate", includeCode: true)

`codegraph_status`

Check index health and statistics.

How It Works With Claude Code

Claude's Explore agents use these tools instead of grep/glob/Read for faster exploration:

Without CodeGraph	With CodeGraph	Benefit
`grep -r "auth"`	`codegraph_search("auth")`	Instant symbol lookup
Multiple `Read` calls	`codegraph_context(task)`	Related code in one call
Manual file tracing	`codegraph_callers/callees`	Call graph traversal
Guessing impact	`codegraph_impact(symbol)`	Know what breaks

This hybrid approach gives you ~30% fewer tokens and ~25% fewer tool calls while letting Claude's native agents handle synthesis.

📚 Library Usage

CodeGraph can also be used as a library in your Node.js applications:

import CodeGraph from '@colbymchenry/codegraph';

// Initialize a new project
const cg = await CodeGraph.init('/path/to/project');

// Or open an existing one
const cg = await CodeGraph.open('/path/to/project');

// Index with progress callback
await cg.indexAll({
  onProgress: (progress) => {
    console.log(`${progress.phase}: ${progress.current}/${progress.total}`);
  }
});

// Search for symbols
const results = cg.searchNodes('UserService');

// Get callers of a function
const node = results[0].node;
const callers = cg.getCallers(node.id);

// Build context for a task
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20,
  includeCode: true,
  format: 'markdown'
});

// Get impact radius
const impact = cg.getImpactRadius(node.id, 2);

// Sync changes
const syncResult = await cg.sync();

// Clean up
cg.close();

⚙️ How It Works

1. Extraction

CodeGraph uses tree-sitter to parse source code into ASTs. Language-specific queries (.scm files) extract:

Nodes: Functions, methods, classes, interfaces, types, variables
Edges: Calls, imports, extends, implements, returns_type

Each node gets a unique ID based on its kind, file path, name, and line number.

2. Storage

All data is stored in a local SQLite database (.codegraph/codegraph.db):

nodes table: All code entities with metadata
edges table: Relationships between nodes
files table: File tracking for incremental updates
node_vectors / vector_map: Embeddings for semantic search (using sqlite-vss)

3. Reference Resolution

After extraction, CodeGraph resolves references:

Match function calls to function definitions
Resolve imports to their source files
Link class inheritance and interface implementations
Apply framework-specific patterns (Express routes, etc.)

4. Semantic Search

CodeGraph uses local embeddings (via @xenova/transformers) to enable semantic search:

Code symbols are embedded using a transformer model
Queries are embedded and compared using cosine similarity
Results are ranked by relevance

5. Graph Queries

The graph structure enables powerful queries:

Callers/Callees: Direct call relationships
Impact Radius: BFS traversal to find all potentially affected code
Dependencies: What a symbol depends on
Dependents: What depends on a symbol

6. Context Building

When you request context for a task:

Semantic search finds relevant entry points
Graph traversal expands to related code
Code snippets are extracted
Results are formatted for AI consumption

⚙️ Configuration

The .codegraph/config.json file controls indexing behavior:

{
  "version": 1,
  "projectName": "my-project",
  "languages": ["typescript", "javascript"],
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "*.min.js"
  ],
  "frameworks": ["express", "react"],
  "maxFileSize": 1048576,
  "gitHooksEnabled": true
}

Options

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)
`gitHooksEnabled`	Enable git hook installation	`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`	Basic support
Kotlin	`.kt`	Basic support

🔧 Troubleshooting

"CodeGraph not initialized"

Run codegraph init in your project directory first.

Indexing is slow

Check if node_modules or other large directories are excluded
Use --quiet flag to reduce console output overhead
Consider increasing maxFileSize if you have large files to skip

MCP server not connecting

Ensure the project is initialized and indexed
Check the path in your MCP configuration is correct
Verify codegraph serve --mcp works from the command line
Check Claude Code logs for connection errors

Missing symbols in search

Run codegraph sync to pick up recent changes
Check if the file's language is supported
Verify the file isn't excluded by config patterns

📄 License

MIT

Made for the Claude Code community 🤖

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
__tests__		__tests__
scripts		scripts
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
IMPLEMENTATION_PLAN.md		IMPLEMENTATION_PLAN.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

colbymchenry/codegraph

Folders and files

Latest commit

History

Repository files navigation

🔮 CodeGraph

Supercharge Claude Code with Semantic Code Intelligence

Get Started

🚀 Why CodeGraph?

📊 Benchmark Results

🔄 How It Works

✨ Key Features

🧠 Smart Context Building

🔍 Semantic Search

📈 Impact Analysis

🌍 15+ Languages

🔒 100% Local

⚡ Always Fresh

🎯 Quick Start

1. Run the Installer

2. Restart Claude Code

3. Initialize Projects

📋 Requirements

💻 CLI Usage

📖 CLI Commands

codegraph / codegraph install

codegraph init [path]

codegraph index [path]

codegraph sync [path]

codegraph status [path]

codegraph query <search>

codegraph context <task>

codegraph hooks

codegraph serve

🔌 MCP Tools Reference

codegraph_context

codegraph_search

codegraph_callers / codegraph_callees

codegraph_impact

codegraph_node

codegraph_status