CodeGraph is a local code knowledge graph designed for AI coding tools. It indexes a project ahead of time and organizes symbol relationships, call graphs, code structure, route relationships, and related information into a queryable graph. That lets Claude Code, Codex CLI, Cursor, OpenCode, Hermes Agent, and similar tools avoid relying on grep, glob, Read, and exploratory subagents every time they need to understand a project.
It solves a very practical problem: when an AI Agent works on a large codebase, much of the cost is not spent on changing code, but on finding where the relevant code lives. If every task starts with repeated searches, reads, and filtering, tokens, time, and tool calls are wasted. CodeGraph tries to turn the repository into a local map first, so the agent can ask the map before deciding which files to read.
What pain points does it address?
AI coding tools usually work well in small projects. There are few files, search is fast, and reading files is cheap. In larger projects, common problems appear:
- The agent repeatedly calls grep, find, ls, and Read just to understand one module.
- Exploratory subagents read many irrelevant files, while the main task context remains unclear.
- Architecture questions spend too many tokens locating files.
- Before changing a function, it is unclear who calls it and what it calls.
- In web projects, URL routes and handler functions are not always obvious.
CodeGraph tries to move this “find the way first” work earlier. Once the project index exists, the agent can query related symbols, callers, callees, impact scope, and code snippets directly.
Installation
The project provides cross-platform installation scripts and does not require users to prepare Node.js manually:
|
|
On Windows PowerShell:
|
|
If you already have a Node environment, you can use npm directly:
|
|
Or install it globally:
|
|
The installer detects and configures installed agents such as Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent. It writes the relevant MCP server configuration and instruction files so those tools know when to call CodeGraph.
Initializing a project
After installation, build an index inside the target project:
|
|
This command creates a project-level knowledge graph index. The README notes that as long as a .codegraph/ directory exists in the project, agents can automatically use CodeGraph tools.
To stop using it, you can remove the global configuration:
|
|
That removes the MCP server configuration, instructions, and permissions written by the installer. The .codegraph/ index in the project is not deleted automatically. To remove the project index, use codegraph uninit.
Why it helps agents
Tools like Claude Code, Codex CLI, and Cursor often explore before making changes: find files, read entry points, inspect references, and follow call chains. For humans this feels like browsing a project. For models, it becomes a series of tool calls and context cost.
CodeGraph turns that into index queries. An agent can first use codegraph_context to find relevant entry points, symbols, and snippets, then use codegraph_explore or other tools to read the necessary details. The benefits are:
- Fewer irrelevant files read.
- Fewer search tool calls.
- Faster discovery of relevant code.
- Clearer impact scope before edits.
- Easier answers to architecture questions in large repositories.
The README reports benchmark results across seven real open source repositories comparing runs with and without CodeGraph. On average, enabling CodeGraph reduced cost, tokens, latency, and tool calls. The exact numbers depend on project size, language, question type, and agent behavior, but the direction is clear: the larger the repository, the more valuable pre-indexing becomes.
Core capabilities
1. Smart context construction
One tool call can return entry points, related symbols, and code snippets, reducing the need for the agent to launch many exploratory tasks before filtering the results. This is useful for architecture understanding, module location, and feature entry-point analysis.
2. Full-text search
CodeGraph uses FTS5 for full-text search, letting it quickly search names and text across the codebase. It does not replace every grep use case, but it gives the agent a more structured first stop.
3. Impact analysis
Before changing a function, class, method, or route, the agent can query callers, callees, and impact radius. This is especially useful for refactoring, bug fixing, and deleting old code, where missing upstream or downstream calls is the main risk.
4. Automatic freshness
The README says CodeGraph uses native filesystem events such as FSEvents, inotify, and ReadDirectoryChangesW, along with debounced auto-sync. In practice, the index updates as local code changes, so users do not need to rebuild it manually after every edit.
5. Multi-language support
The project lists support for more than 19 languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, and Pascal / Delphi.
That makes it suitable for multi-language repositories and full-stack projects, not just one language.
6. Web route awareness
CodeGraph also detects route files and route declarations in many web frameworks, connecting URL patterns with handler functions. The README mentions Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, Axum, ASP.NET, Vapor, React Router, SvelteKit, and others.
This is practical because the real entry point of many web projects is not an obvious main function, but routes, controllers, handlers, views, or resolvers. If an agent can first understand the URL-to-handler relationship, it can understand business flow much faster.
Local-first design
CodeGraph emphasizes being 100% local. It does not require an API key or external service. Index data is stored in a local SQLite database.
For enterprise projects, private repositories, or sensitive code, this matters. The concern with AI coding tools is often not only “can they find the code?”, but “will the code structure and index be sent elsewhere?” CodeGraph is positioned as local indexing, local querying, and local service for agents.
Of course, local indexing also means considering disk usage, indexing time, file watching, and project size. Very large repositories still require resources for initial indexing and later synchronization.
Suitable scenarios
CodeGraph is a good fit for:
- Large codebases where architecture and call-chain questions are common.
- Teams using Claude Code, Codex CLI, Cursor, or similar agents for code understanding and edits.
- Reducing random file reads, broad searches, and repeated exploration by agents.
- Analyzing impact before code changes.
- Web projects with complex routing, where URL-to-handler lookup matters.
- Teams that want a more stable local project index for AI agents.
For a small project with a few dozen files, normal search may be enough and CodeGraph’s advantage may not be obvious. It is most valuable in medium-to-large repositories and workflows where agents do a lot of exploration.
Things to watch out for
First, CodeGraph is not a substitute for code review or testing. It helps agents find relevant code faster, but it does not guarantee that their changes are correct.
Second, index quality affects results. If a project has complex structure, lots of generated code, mixed languages, or unignored build artifacts, the index may become noisy. Before using it seriously, check .gitignore, project layout, and indexing scope.
Third, MCP configuration and agent instructions matter. The README also warns that CodeGraph helps only when it is queried properly. If an agent ignores it and still reads many files directly, pre-indexing becomes extra overhead.
Fourth, even though it is local, permissions still matter. The installer writes agent configuration and permission lists. In team environments, review those configurations centrally.
Summary
CodeGraph can be understood simply: it gives AI agents a local map of the codebase. It does not make the model smarter; it helps the model get less lost.
When tools like Claude Code, Codex CLI, and Cursor face large repositories, the expensive part is often exploration. CodeGraph uses pre-indexed symbol relationships, call graphs, route graphs, and full-text search to handle “where is the code?” earlier, leaving more budget for understanding and editing.
If you already use AI coding tools in real projects and often see the agent read many files without finding the point, CodeGraph is worth trying. It represents an important direction for AI coding tools: not only stronger models, but better local code context for those models.
References:
- GitHub project: https://github.com/colbymchenry/codegraph