Working with AI-powered coding assistants has an uncomfortable side that many developers have already experienced: before suggesting a solution, the model needs to understand the project. And to understand it, it usually has to walk through files, search for symbols, run grep queries, open modules, review imports and ask for context again and again. Each of those operations consumes time, tool calls and, in many cases, tokens.
CodeGraph was created to reduce that cost. The project, available on GitHub under an MIT licence, builds a local semantic graph of the code so that tools such as Claude Code, Cursor, Codex CLI and OpenCode can query the structure of a project without exploring everything from scratch for every task. The idea is simple: index the repository once, store relationships between symbols, calls, imports, classes, methods and routes, and allow the agent to query that local database whenever it needs context.
The approach fits a clear trend in AI-assisted development. As projects grow, it is no longer enough to give the model a folder and ask it to “understand” the code. Context becomes expensive, searches are repetitive and agents can waste time reading files that add little value. A local semantic index reduces that initial exploration and helps the AI reach the relevant parts sooner.
What CodeGraph does and why it can save tokens
CodeGraph works as an intelligence layer on top of the repository. It analyses the code with tree-sitter, extracts nodes such as functions, classes, methods or files, and creates relationships between them: calls, imports, inheritance, implementations and references. Everything is stored in a SQLite database inside the project, in .codegraph/codegraph.db, with full-text search powered by FTS5.
This means that when an agent needs to find where login is implemented, which functions call a service, or which tests might be affected by a change, it does not need to scan the entire file tree. It can query the graph.
According to the figures published by the project, its benchmarks across six real repositories show an average of 92% fewer tool calls and 71% faster code exploration. The repository header also highlights measurements of up to 94% fewer calls and a 77% improvement in exploration speed, although these figures should be read as the project’s own results, not as a universal guarantee for every codebase.
| Tested project | With CodeGraph | Without CodeGraph | Reported improvement |
|---|---|---|---|
| VS Code | 3 calls, 17 s | 52 calls, 1 min 37 s | 94% fewer calls, 82% faster |
| Excalidraw | 3 calls, 29 s | 47 calls, 1 min 45 s | 94% fewer calls, 72% faster |
| Claude Code, Python + Rust | 3 calls, 39 s | 40 calls, 1 min 8 s | 93% fewer calls, 43% faster |
| Claude Code, Java | 1 call, 19 s | 26 calls, 1 min 22 s | 96% fewer calls, 77% faster |
| Alamofire | 3 calls, 22 s | 32 calls, 1 min 39 s | 91% fewer calls, 78% faster |
| Swift Compiler | 6 calls, 35 s | 37 calls, 2 min 8 s | 84% fewer calls, 73% faster |
The benefit is not only about saving tokens. It also improves workflow. An agent that understands the project sooner can spend more time reasoning about the change and less time rebuilding the architecture mentally. In refactoring, bug fixing or impact analysis tasks, that can make a noticeable difference.
Local, open source and compatible with several agents
One of CodeGraph’s strongest points is that it runs locally. It does not require API keys, does not send code to external services and stores the index in SQLite. For teams working with private repositories, intellectual property or client code, this detail matters. AI itself may already raise privacy questions, but at least the project-indexing layer does not add another external dependency.
Installation is designed to be quick. The initial command is:
npx @colbymchenry/codegraph
The interactive installer detects compatible agents and can configure Claude Code, Cursor, Codex CLI or OpenCode. Then, inside the project, you simply run:
codegraph init -i
That command creates the local index and prepares the repository so the agent can use CodeGraph automatically when it detects the .codegraph/ directory.
There are also non-interactive installation options, useful for scripting or CI environments, and manual commands to index, sync, query symbols, list files, build context or analyse which tests are affected by specific changes.
CodeGraph also exposes MCP tools, allowing compatible agents to query the graph in a structured way. These include codegraph_search, to search for symbols; codegraph_context, to build useful context for a task; codegraph_callers and codegraph_callees, to inspect incoming and outgoing calls; codegraph_impact, to analyse the impact radius of a change; and codegraph_files, to retrieve the indexed project structure without scanning the filesystem.
Languages, frameworks and web routes
Language coverage is broad. CodeGraph declares full support for TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid and Pascal/Delphi, among others. This makes it useful for modern web applications as well as backend repositories, systems tools, SDKs and mobile projects.
Another interesting feature is its support for web framework routes. CodeGraph can recognise routing patterns in Django, Flask, FastAPI, Express, Laravel, Rails, Spring, Gin, chi, gorilla/mux, Axum, actix, Rocket, ASP.NET, Vapor, React Router and SvelteKit. In practice, this makes it possible to connect URLs or routes to their corresponding handlers, which is very useful when an agent needs to understand how an HTTP request reaches a specific function.
For example, if an AI has to modify the behaviour of a view, finding the method is not always enough. It also needs to know which route invokes it, which middleware may intervene, which controller wraps it and which other points depend on that symbol. A code graph helps answer those questions with less repeated exploration.
The tool also includes automatic syncing. The MCP server watches project changes using native operating system events such as FSEvents, inotify or ReadDirectoryChangesW, and updates the index incrementally after a short debounce window. This prevents the graph from becoming outdated every time a file is saved.
Where it fits, and where caution is needed
CodeGraph can be especially useful in medium or large repositories, teams that use coding agents every day, projects with many modules or applications where code exploration cost is becoming obvious. It can also help with onboarding, impact analysis and selecting tests affected by changes.
It does not replace developer judgement or make AI infallible. The graph can speed up context retrieval, but the model still has to interpret the intent of the change correctly. It is also important to monitor index quality, excluded folders, maximum file size and the SQLite backend. The project itself warns that if the WASM SQLite version is used instead of the native better-sqlite3 backend, performance can be 5 to 10 times slower and database locks may appear during indexing.
The configuration allows teams to exclude folders such as node_modules, dist or build, define languages, enable docstring extraction and control call-site tracking. In large projects, tuning these options properly will be important to avoid unnecessarily heavy indexes.
The bigger lesson is clear: the future of AI-assisted development will not depend only on larger models. It will also depend on better tools for giving those models context. An agent that understands the structure of a project without reading the whole thing for every request works with less noise, lower cost and greater precision. CodeGraph points exactly in that direction: turning the repository into a local, queryable map built for agents.
Frequently asked questions
What is CodeGraph?
CodeGraph is an open source tool that creates a local semantic graph of a codebase so that AI agents such as Claude Code, Cursor, Codex CLI and OpenCode can better understand a project without exploring it from scratch.
Does CodeGraph send code to the cloud?
No. According to the project documentation, it runs locally, requires no API keys and stores the index in a SQLite database inside the project.
What advantages does it offer compared with normal grep searches?
Beyond text search, CodeGraph understands symbols, calls, imports, class relationships and framework routes. This allows it to build more useful context for AI-assisted programming tasks.
Which languages does CodeGraph support?
It supports more than 19 languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Vue and Pascal/Delphi.