CodeGraph: Pre-Indexed Code Graph for AI Coding Agents

CodeGraph: Semantic Code Intelligence for Local AI Coding Agents

Introduction

CodeGraph is a self-contained, zero-config layer of semantic code intelligence designed to supercharge your coding agents—Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent. The core idea is simple but powerful: instead of every agent scanning files on the fly with grep or Read operations, CodeGraph builds and maintains a local semantic knowledge graph of your codebase. This graph captures symbol relationships, call graphs, and structural patterns, enabling agents to answer questions instantly from indexed knowledge rather than performing costly file reads.

Key benefits at a glance:

Approximately 35% cheaper on average
About 70% fewer tool calls
100% local—no data leaves your machine
Self-contained runtime with pre-bundled Node
Cross-platform support (Windows, macOS, Linux)
Multi-language coverage across popular stacks

A Snapshot of the Ecosystem

CodeGraph is designed to plug into your existing AI workflow with minimal friction. The installer walks you through configuring the MCP server and wiring up the agents you use. The data remains on your machine, stored in a local SQLite graph database, with full-text search powered by FTS5.

If you glance at the project’s visuals, you’ll notice the active ecosystem of agents and the breadth of language support. A stand-out visual shows the one-command installation flow, aligning all agents and preparing them to query the local knowledge graph rather than re-reading files.

A single snapshot from the project attachments highlights the initial interface and the agents in play.

Get Started: No Node.js Required

CodeGraph embraces a fast, one-command path to the right build for your OS. You don’t need Node.js to begin; the installer fetches the appropriate build and configures your environment automatically.

macOS / Linux (curl-based installer)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

If you already have Node, you can use npm or npx for a zero-install experience:

npx @colbymchenry/codegraph
or: npm i -g @colbymchenry/codegraph

CodeGraph bundles its own runtime—no native builds, no per-project compilation. The interactive installer auto-configures your agent(s): Claude Code, Cursor, Codex CLI, opencode, Hermes Agent.

Initialize Projects

Once installed, you’ll typically initialize a project with:

cd your-project
codegraph init -i

This step builds the per-project knowledge graph index and wires up any project-local agent surfaces so that a single global codegraph install works across projects.

A Snapshot in Use

A representative image from the project demonstrates the integration and the way the agents surface knowledge from the index rather than scanning files anew.

1CVYnhpys0UHrOuOgpgoyw

Uninstall: Reversing the Installer

Changed your mind? You can remove CodeGraph from every agent it configured with a single command:

codegraph uninstall

This reverses the installer, stripping MCP server configs, instructions, and permissions from each configured agent. Your project indexes (.codegraph/) are left intact for safety; you can remove those on a per-project basis with:

codegraph uninit

If you want to target a subset of agents, you can specify --target and you can run in non-interactive mode with --yes.

Why CodeGraph? The Problem It Solves

Claude Code, when exploring a codebase, typically spawns Explore agents that scan files via grep, globbing, and Read operations. Each of those actions consumes tokens and incurs tool calls. CodeGraph changes the economics by providing a pre-indexed knowledge graph—symbol relationships, call graphs, and code structure—that the agents can query instantly.

In practical terms, CodeGraph reduces the tax paid by agents during exploration. The benchmarking across seven real-world codebases shows:

Average savings: 35% cheaper
59% fewer tokens processed
49% faster responses
70% fewer tool calls

Real-world benchmarks span languages and frameworks:

VS Code: TypeScript, ~10k files — 35% cheaper, 73% fewer tool calls, 41% faster
Excalidraw: TypeScript, ~600 files — 47% cheaper, 73% fewer tool calls, 60% faster
Django: Python, ~2.7k files — 34% cheaper, 64% fewer tool calls, 59% faster
Tokio: Rust, ~700 files — 52% cheaper, 81% fewer tool calls, 63% faster
OkHttp: Java, ~640 files — 17% cheaper, 41% fewer tool calls, 36% faster
Gin: Go, ~150 files — 22% cheaper, 23% fewer tool calls, 34% faster
Alamofire: Swift, ~100 files — 38% cheaper, 59% fewer tool calls, 51% faster

The gains scale with codebase size. In large repositories, the agent can answer directly from the index with minimal file reads, often in a handful of calls. In contrast, a no-CodeGraph agent tends to fan out across grep/find/Read and its sub-agents, allocating more budget to discovery than to analyzing the code. The takeaway: CodeGraph shines when asked targeted questions that leverage indexed context, not when simply browsing raw files.

Full Methodology, Raw Medians, and Why It Works

The benchmark approach used Claude models (Opus 4.7, Code v2.1.145), headless, with a strict MCP config. The two arms—WITH (CodeGraph MCP server enabled) and WITHOUT (empty MCP config)—were run four times per arm, and the medians reported. Costs and timings reflect the run’s total cost in USD, total tokens processed, wall-clock time, and the number of tool invocations. Repositories were cloned and indexed with consistent depth to ensure comparability.

Key takeaway: with the knowledge graph in place, the agent can map the area, locate relevant source quickly, and stop after a targeted exploration step—often avoiding unnecessary file reads.

Key Features That Distinguish CodeGraph

Smart Context Building
A single tool call yields entry points, related symbols, and code snippets—no expensive, broad exploration.
Full-Text Search
Instantly find code by name across the entire codebase, powered by SQLite FTS5.
Impact Analysis
Trace callers, callees, and the full impact radius of any symbol before making changes.
Always Fresh
Native OS file-watching with debounced auto-sync keeps the graph current as you code.
Broad Language Coverage
19+ languages including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi, and more.
Framework-aware Routes
Recognizes routing files and links URL patterns to handlers across 14 web frameworks.
100% Local
No data leaves your machine; no API keys; SQLite is the store.

Framework-aware Routes: How CodeGraph Interprets Framework Files

CodeGraph detects routing configurations and emits route nodes linked to their handler classes or functions. This makes it possible to query for the URL pattern tied to a given view or controller. Recognized frameworks include:

Django: path, re_path, url, include; class-based views and dotted paths
Flask: app.route, blueprint routes
FastAPI: get/post routers
Express: app.get, router.post with middleware
NestJS: @Controller and @Get/@Post/…, GraphQL @Resolver, @Query/@Mutation, and more
Laravel: Route::get, Route::resource, Controller@action
Drupal: *.routing.yml and hook implementations
Rails: get '/x', to: 'users#index', hash-rocket style
Spring: @GetMapping, @PostMapping, @RequestMapping
Gin / chi / gorilla / mux: r.GET, router.HandleFunc
Axum / actix / Rocket: route patterns
ASP.NET: [HttpGet("/x")] attributes
Vapor: app.get("x", use: handler)
And more for React Router, SvelteKit, etc.

The result is a graph that connects routes to their handlers, enabling instant insight into how a request flows through your codebase.

Quick Start: A Practical Path

1) Run the Installer

npx @colbymchenry/codegraph
The installer detects installed agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent) and prompts to install codegraph on PATH (so the MCP server can run).
It can apply configs globally or per project, and write agent-specific instruction files (CLAUDE.md, .cursor/rules/codegraph.mdc, ~/.codex/AGENTS.md).
For non-interactive environments: codegraph install --yes or targeting specific agents with codegraph install --target=cursor,claude --yes.

2) Restart Your Agent

After installation, restart Claude Code, Cursor, Codex CLI, opencode, or Hermes Agent to load the MCP server.

3) Initialize Projects

cd your-project
codegraph init -i
This creates the per-project index and wires in project-local agent surfaces, so a single global codegraph install works across projects.

Manual Setup (Alternative)

If you prefer manual setup, you can install globally:

npm install -g @colbymchenry/codegraph

And add to Claude’s config:

Add to ~/.claude.json:
A snippet that wires the MCP server for codegraph via stdio and the serve command.

Alternatively, you can add to Claude’s optional auto-allow settings to streamline permissions.

How CodeGraph Works: A High-Level View

CodeGraph operates as an MCP-backed knowledge plane. A typical flow looks like this:

Extraction: A tree-sitter-based parser converts source files into ASTs; language-specific queries extract nodes (functions, classes) and edges (calls, imports).
Storage: The data gets stored in a local SQLite database (.codegraph/codegraph.db) with FTS for fast searching.
Resolution: References are resolved — function calls map to definitions, imports to files, inheritance patterns, and framework-specific patterns.
Auto-Sync: The MCP server watches the project via native OS file events; changes are debounced and incrementally synced to keep the graph fresh.

The practical benefits are clear: faster context, targeted exploration, and zero-config operation.

A Visual: How It Looks Under the Hood

To illustrate the architecture, imagine a simplified diagram:

Claude Code (or various agents) asks for “Implement user authentication.”
An Explore Agent would ordinarily search, read, and extract, but CodeGraph places a pre-indexed graph in between.
The MCP Server queries a local SQLite graph database for relevant symbols, calls, and context, returning concise results to the AI.
The graph is kept current via incremental syncing, so the next question benefits from up-to-date context.

This visual helps explain why CodeGraph reduces file reads and accelerates responses, especially on large repositories.

CLI Reference: A Compact Guide

CodeGraph exposes a compact command-line interface for setup, indexing, and querying:

codegraph: Run the interactive installer
codegraph install: Install or configure CodeGraph for agents
codegraph uninstall: Remove CodeGraph from configured agents
codegraph init [path]: Initialize in a project (or --index to index)
codegraph uninit [path]: Remove CodeGraph from a project
codegraph index [path]: Full index (reindex with --force)
codegraph sync [path]: Incremental update
codegraph status [path]: Show index statistics
codegraph query: Search symbols (options for kind, limit, json)
codegraph files [path]: Show file structure
codegraph context: Build context for AI queries
codegraph callers / codegraph callees: Trace call flows
codegraph impact: Analyze what changes affect
codegraph serve --mcp: Start the MCP server

A practical usage snippet:

codegraph init -i
codegraph status
codegraph query "getUserProfile"

CodeGraph in Library Form

Developers can use CodeGraph as a library. A TypeScript example shows the core interactions:

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(); cg.close();

Configuration and Zero-Config Philosophy

CodeGraph embraces zero-config operation. It indexes files based on language extensions and respects .gitignore rules. In git repos, ignored files (node_modules, build outputs, secrets) are never indexed. Projects outside git ignore can still be managed, but the same principle applies: add sensitive or unnecessary paths to .gitignore to keep them out of the graph.

What’s Supported

Platforms: Windows, macOS, Linux with self-contained builds for x64 and arm64 architectures.
Agents: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent are auto-detected and wired up during installation.
Languages: A broad list spanning TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, and Pascal/Delphi, plus more like Scala, Dart, and various web frameworks.
Frameworks: The routing-aware features recognize Django, Flask, FastAPI, Express, NestJS, Laravel, Drupal, Rails, Spring, Gin/chi/gorilla/mux, Axum/Actix/Rocket, ASP.NET, Vapor, React Router, SvelteKit, and more.

Troubleshooting: Quick Remedies

“CodeGraph not initialized”: Run codegraph init in the project directory.
Indexing is slow: Exclude large directories like node_modules; use --quiet to reduce output.
MCP database locked: Ensure you’re on a recent installation; if needed, reinstall or upgrade to the bundled runtime. If WAL cannot be enabled on your filesystem (e.g., network shares, WSL2), move to local disk.
MCP server not connecting: Verify project initialization/indexing and the MCP config path; ensure codegraph serve --mcp runs from the command line.
Missing symbols: The MCP server auto-syncs on save; if not, run codegraph sync or verify language support and ignore patterns.

A Growth Story: Community Momentum and History

CodeGraph has seen growing adoption in AI coding workflows. The project’s momentum is captured by a star-history visualization that tracks community engagement over time.

Star History Chart

License and Rights

CodeGraph is released under the MIT license. It is designed to be fully self-contained—packaging its own Node runtime so users don’t need to install a separate Node environment. This makes it especially friendly for environments where dependencies must be tightly controlled or where onboarding speed matters.

A Visual Highlight: The Project’s Momentum

The project’s gallery of visuals includes a prominent depiction of the one-command installer flow, the MCP server’s concept, and the relationships between the agent surfaces and the local graph. The visuals reinforce the concept of a self-contained, local, and fast code intelligence layer that sits between AI assistants and your code.

Closing Thoughts: Why You Should Try CodeGraph

If you’re building AI-assisted workflows where latency, token efficiency, and data locality matter, CodeGraph offers a compelling value proposition. It gives your agents a pre-indexed understanding of your codebase, dramatically reducing the need for repeated, expensive file scans. The result is faster answers, lower costs, and a more seamless developer experience.

From installation to project-wide indexing, from framework-aware routing to language-wide coverage, CodeGraph is engineered to be practical, fast, and privacy-respecting. The combination of a local SQLite-backed knowledge graph, smart context resolution, and robust MCP tooling makes it a strong foundation for AI-powered software development.

Images from the Input, Integrated Here

The initial set of badges and status indicators echoes the project’s cross-platform, license, and agent support. [] [] [] [] [] [] [] [] [] [] []

The project’s illustration of a typical run—installing, configuring, and indexing a project—appears in the Input as well as the broader narrative of how the installer connects agents to the MCP server.

The Star History image shows community momentum and is referenced above to convey the project’s growth and adoption.

Final Note

CodeGraph is a versatile, local-first layer for semantic code intelligence. It is designed to work with multiple agents, across dozens of languages, and across major frameworks. Its zero-config philosophy reduces friction, and its robust benchmarking suggests tangible efficiency gains in real-world usage. Whether you’re building AI-assisted tooling, enhancing a code review workflow, or enabling faster exploration in your own development environment, CodeGraph offers a practical pathway to smarter, cheaper, and faster code understanding—all while keeping your data on-device.