What is CodeGraph
CodeGraph is a pre-indexed code knowledge graph tool for AI coding agents, deeply integrated with Claude Code、Cursor、Codex CLI、OpenCode and Hermes Agent through the MCP protocol. It uses tree-sitter to parse codebases, storing symbol relationships, call graphs, and code structure in a local SQLite database, enabling AI agents to directly locate code through graph queries instead of traditional grep/glob/Read file scanning methods. Verified by benchmarks on 7 real open-source projects, CodeGraph can on average reduce API costs by 35%, cut Token consumption by 59%, save 49% of time, and reduce the number of tool calls by 70%, all running 100% locally without the need for external API keys.
CodeGraph's main features
-
Pre-indexed code knowledge graph: Uses tree-sitter to parse codebases into ASTs, extracting symbol nodes such as functions, classes, and methods, along with relationship edges such as calls, imports, and inheritance, to build an instantly queryable SQLite graph database.
-
Intelligent context building: A single tool call returns entry points, related symbols, and code snippets, without the need for expensive exploration agents to scan file by file.
-
Full-text symbol search: Instant search of symbol names across the codebase based on FTS5, quickly locating target code.
-
Impact radius analysis: Tracks the callers, callees, and full impact scope of any symbol, assessing the extent of impact before making changes.
-
Framework-aware routing: Automatically identifies routing files of 14 Web frameworks, associating URL patterns with the corresponding handler functions/classes.
-
Real-time automatic sync: Monitors project changes through native OS file events (FSEvents/inotify/ReadDirectoryChangesW), automatically incrementally syncing the graph after a 2-second debounce.
-
Change impact test tracking：
codegraph affectedcommand can track the transitive dependencies of changed files, precisely locating affected test files, suitable for CI pipelines. -
Zero-configuration, ready to use: Automatically identifies languages based on file extensions, automatically respects
.gitignorerules, with no need to write any configuration files.
How to use CodeGraph
-
Install CodeGraph: Execute in the terminal
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh(macOS/Linux) orirm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex(Windows PowerShell); users who already have Node.js installed can also directly runnpx @colbymchenry/codegraph -
Select integration agent: The installer automatically detects AI agents already installed on the system (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent), interactively prompts you to select the agent to configure, and automatically writes the MCP configuration
-
Restart AI agent: After installation is complete, restart the corresponding AI agent to make the MCP server configuration take effect
-
Initialize project index: Enter the project directory and execute
codegraph init -i, to build the knowledge graph index for that project; it will also automatically configure project-level agent rule files (such as.cursor/rules/codegraph.mdc） -
Start using: When a
.codegraph/folder exists in the project directory, the AI agent will automatically call CodeGraph tools for code querying and exploration; you can also manually query through the CLI by executingcodegraph query <关键词>、codegraph callers <符号名>and other commands
CodeGraph's core advantages
-
Significantly reduce usage costs: Tested on 7 real open-source projects (VS Code, Excalidraw, Django, Tokio, OkHttp, Gin, Alamofire), it saves an average of 35% in API costs, 59% in token consumption, 49% in execution time, and 70% in the number of tool calls; the effect is especially pronounced on large repositories.
-
100% Local Privacy and Security: All data is stored in a local SQLite database, with no internet connection, no API key, and no data upload required, fully safeguarding code privacy.
-
Cross-Platform, Self-Contained Operation: Provides standalone build packages for Windows (x64/arm64), macOS (x64/arm64), and Linux (x64/arm64), with a built-in Node runtime and no need for local compilation or additional installation of Node.js.
-
Full Coverage of 19+ Languages: Full support for mainstream and niche languages including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid, Pascal/Delphi, Lua, Luau, and more.
-
Deep Framework Integration: Natively recognizes the routing syntax of 14 frameworks including Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, React Router, SvelteKit, and more, precisely associating URLs with handlers.
-
Seamless Agent Integration: Connects with mainstream AI coding agents through the MCP protocol; the installer completes configuration automatically, with no need to manually edit JSON configuration files.
CodeGraph's project address
- GitHub repository：https://github.com/colbymchenry/codegraph
CodeGraph's application scenarios
-
Quick Answers to Architecture Questions: Ask the AI agent architecture-level questions such as "How does the extension host process communicate with the main process?" The agent directly locates the relevant source code through the graph, with no need for divergent file scanning.
-
Code Review and Impact Analysis: Before modifying a core function, analyze the scope of the change through
codegraph_impactto avoid introducing regression issues. -
Onboarding and Code Familiarization: New team members ask the AI agent questions in natural language to quickly understand the project structure, module dependencies, and key business logic.
-
Precise Test Targeting: In the CI pipeline, combine
git diffwithcodegraph affectedto run only the test files affected by code changes, shortening build time. -
Cross-File Refactoring Assistance: When refactoring a public API, use callers/callees to track all reference points across the repository, ensuring all call sites are updated in sync.