CodeGraph: Code Knowledge Graph for AI Agents — 94% Fewer Tool Calls

When AI coding agents explore a codebase, they work with classic methods: reading file by file, grep/searching, trying to understand the project structure. This process burns tons of tokens and wastes valuable context window space.

CodeGraph solves this problem at its root: it parses code at the AST level and saves it into a SQLite knowledge graph. The agent makes instant queries to this graph via MCP, reducing exploration that would take seconds down to milliseconds.

Instantly query your codebase at the symbol level with CodeGraph

The Problem: Agents Get Lost in the Codebase

Typical steps an AI coding agent takes to understand a new project:

1. Explore file structure (ls, glob)
2. Read relevant files (read)
3. Find function/class definitions (grep patterns)
4. Extract call graphs (reading multiple files)
5. Understand dependencies (import/export chain)

Each step burns tool calls + tokens. In large projects, this process takes minutes and fills most of the context window with unnecessary file content.

The Solution: CodeGraph

CodeGraph (@colbymchenry/codegraph) is a pre-indexed code knowledge graph for AI coding agents. One-line setup:

npx @colbymchenry/codegraph
# → Interactive setup: Claude Code, Cursor, Codex, OpenCode integration

cd your-project
codegraph init -i
# → Parses entire codebase from AST and indexes into SQLite

How It Works

Codebase → AST Parser (19+ languages) → Symbol Graph → SQLite (.codegraph/)
                                                       ↓
                                              MCP Server (instant queries)
                                                       ↓
                                         Claude Code / Cursor / Codex / OpenCode

Supports 19+ programming languages: TypeScript, Python, Rust, Go, Java, C++, Swift, Ruby, PHP, and more.

MCP Tools: The Agent’s New Superpower

CodeGraph offers 7 specialized tools via MCP (Model Context Protocol):

CLI Commands

Also usable directly from terminal:

# Search symbol
codegraph query "authenticateUser"

# Create task context (markdown output)
codegraph context "move login page to next.js"

# Show file structure
codegraph files

# Impact analysis
codegraph affected src/services/auth.ts

# Start as MCP server
codegraph serve

# Visualization (opens in browser)
codegraph visualize

# Index status
codegraph status

Benchmark: Numbers Speak

Official CodeGraph benchmark results:

What these numbers mean:

• Agent makes 1 tool call instead of 10 tool calls
• Minutes-long exploration takes seconds
• Context window is filled with real code knowledge, not empty files

Framework Support: 13+ Web Framework Recognition

CodeGraph understands not only symbols but also framework routing structures:

When changing an Express route, you can instantly see which middlewares, controllers, and views are affected.

Real-World Use Cases

1. Fast Exploration in Paperclip Codebase

When working on the Paperclip EBA framework, I frequently need to add new features. With CodeGraph:

codegraph context "add a new data source to the lead enrichment pipeline"

Shows all relevant files, functions, and dependencies in a single query. Exploration that would normally take minutes takes seconds.

2. Impact Analysis in Hermes War Room

When making a change in the Hermes Orchestration War Room:

codegraph impact "KanbanBoard"

Instantly shows which components, API routes, and database queries are affected. When you change the kanban_create skill, you can see its reflections across all profiles.

3. Dependency Management in Neo4j Projects

When a function changes in projects like MomYachting or Hermes Memory:

codegraph callers "text_to_cypher.convert"
codegraph search "CypherQueryBuilder"

See at once who calls the function, which tests are affected, and which routes use this function.

Why It’s Different from Other Solutions

Notable Technical Details

AST-Level Parsing

CodeGraph parses code not as strings but at the AST (Abstract Syntax Tree) level. This means:

// CodeGraph understands this not as a "function declaration"
// but as an "async arrow function with two params, exported"
export const authenticateUser = async (email: string, password: string) => {
  const user = await db.users.findByEmail(email);
  return user && compare(password, user.hash);
};

FTS5 Full-Text Search

Thanks to SQLite’s FTS5 (Full-Text Search) engine, symbol searches are instant:

codegraph_search "auth" → authenticateUser, isAuthenticated, authMiddleware, AuthGuard, authRoutes...

Native OS File Watcher

File changes are automatically indexed with debounced file watching. No need to call codegraph sync manually.

100% Local, Zero External Dependencies

No API key, cloud service, or third-party dependencies. Everything is stored in SQLite under the .codegraph/ directory.

Setup Guide

# 1. Install CodeGraph
npx @colbymchenry/codegraph
# → Interactive setup begins
# → Claude Code, Cursor, Codex, OpenCode integrations
# → MCP server settings auto-configured

# 2. Index your project
cd /path/to/project
codegraph init -i

# 3. Test it
codegraph status
codegraph files
codegraph query "yourFunction"

# 4. (Optional) Start MCP server
codegraph serve

Note: After running codegraph init in your project, a .codegraph/ directory is created. Don’t forget to add it to .gitignore.

Conclusion

CodeGraph fundamentally changes how AI coding agents understand your codebase. Agents no longer need to read file by file, grep, or try to figure out project structure.

Summary:

• 94% fewer tool calls means faster agents
• 77% faster exploration means near-zero waiting time
• 100% local ensures data security
• 19+ languages, 13+ frameworks works with almost any project
• MCP native seamless integration with Claude Code, Cursor, Codex, OpenCode

I use it in my own projects — fast exploration in the Paperclip codebase, impact analysis in Hermes War Room, and dependency tracking in Neo4j pipelines. It’s already made it to my indispensable tools list.

Resources

• CodeGraph GitHub
• CodeGraph NPM
• Model Context Protocol (MCP)
• SQLite FTS5
• Claude Code
• Hermes Agent

Hero image in this article was generated with fal.ai + FLUX.1 Dev.