Code Knowledge Graph: Pre-Indexed with CodeGraph for AI Assistants

AI coding assistants like Claude Code and Cursor often waste tokens navigating unfamiliar codebases. CodeGraph changes that by pre-indexing your project into a local knowledge graph—symbol relationships, call graphs, and framework routes—so the assistant can answer complex queries in one or two tool calls instead of dozens. The result? Up to 94% fewer tool calls and 71% faster exploration, all 100% local.

What is CodeGraph?

CodeGraph is an open-source CLI tool built in TypeScript that scans your codebase and builds a SQLite-backed knowledge graph of symbols, their relationships, and call chains. It integrates directly with Claude Code, Cursor, Codex CLI, and OpenCode via an MCP (Model Context Protocol) server. Instead of having the AI agent comb through files with primitive tools, CodeGraph exposes a codegraph_explore function that returns exactly the nodes and edges needed to answer the query—entry points, related symbols, and even code snippets.

How CodeGraph Works

• Indexing phase: CodeGraph parses your codebase using language-specific AST parsers (supports 19+ languages, including TypeScript, Python, Rust, Go, Java, Swift) and extracts symbols (classes, functions, variables), their definitions, and references.
• Graph construction: All symbols become nodes, and relationships (calls, imports, extends, implements, framework routes) become edges. The graph is stored locally in a SQLite database with FTS5 full-text search.
• Query phase: The AI assistant calls codegraph_explore with a natural language query or symbol name. CodeGraph returns a subgraph of relevant nodes and edges, plus code snippets—no file system scanning needed.
• Real-time sync: A background watcher detects file changes and incrementally updates the graph, ensuring the assistant always sees the latest code.

Quick Start Guide

1. Run the interactive installer:

npx @colbymchenry/codegraph

The installer auto-detects your installed agents (Claude Code, Cursor, Codex CLI, OpenCode) and configures them to use CodeGraph. It also installs the codegraph command on your PATH.

2. Initialize a project index:

cd your-project
codegraph init -i

This parses your code and creates the graph.

3. Use the AI assistant as normal. When the assistant needs to explore code, it will call codegraph_explore instead of spawning an explore agent. You'll see dramatically fewer tool calls and faster responses.

Real-World Performance

In a test on the VS Code codebase (4,002 TypeScript files), Claude Code's Explore agent made 52 tool calls, read ~15 files, and took 1 minute 37 seconds. With CodeGraph, it made 3 tool calls and finished in 17 seconds—94% fewer calls and 82% faster. The query was "How does the extension host communicate with the main process?" and the agent never fell back to reading files because the graph traversal gave it the complete call chain.

Here's what the agent saw under the hood (simplified):

codegraph_explore(
  query: "extension host communication main process",
  depth: 3
)
// Returns: subgraph with nodes [ExtensionHost, MainProcess, ipcRenderer, ipcMain, ...],
// edges [calls, communicatesVia, implements], and code snippets for key functions.

The benchmarks in the README show similar gains across six diverse codebases.

The Verdict: Pros, Cons, and Alternatives

Pros

• Massive token and time savings: 94% fewer tool calls, 71% faster on average (based on rigorous benchmarks).
• 100% local: No data leaves your machine; no API key needed.
• Auto-sync: File watchers keep the graph fresh without manual reindexing.
• Multi-framework route awareness: Detects URL patterns for Django, Flask, Express, Rails, Spring, and more, linking routes to handlers.
• Cross-language support: Graph traversal works across multiple languages in one project.

Cons

• Initial indexing time: For very large codebases (e.g., Swift Compiler with 25,874 files), indexing can take a few minutes (one-time cost).
• Limited to supported languages: If your project uses a language not in the 19+ list, it won't be indexed (though many popular languages are covered).
• MCP protocol dependency: Currently works only with agents that support MCP (Claude Code, Cursor, Codex CLI, OpenCode).

Alternatives

• Sourcegraph Cody: Commercial AI assistant with code graph features, but requires cloud connection and API key. Not lean for local-only workflows.
• Aider's --map-refine: Provides a high-level code map but less granular than a full knowledge graph and lacks auto-sync.
• Manual prompt engineering: Brittle and doesn't scale across large projects.

Should You Use CodeGraph?

CodeGraph is a must-have if you're already using Claude Code, Cursor, Codex, or OpenCode and regularly explore unfamiliar codebases. The token savings alone justify the setup—in tests, token usage dropped by nearly half. Skip it if your project is very small (under 50 files) or uses unsupported languages. But for anyone dealing with a real-world codebase of any complexity, CodeGraph is a rare win: free, local, and measurably faster.