CodeGraph 是一个给 AI 编程工具使用的本地代码知识图谱。它会提前给项目建立索引，把符号关系、调用图、代码结构、路由关系等信息整理成可查询的图，让 Claude Code、Codex CLI、Cursor、OpenCode、Hermes Agent 这类工具不用每次都靠 grep、glob、Read 和子代理到处翻文件。
它解决的是一个很实际的问题：AI Agent 看大型代码库时，很多成本不是花在真正修改代码上，而是花在“找代码在哪里”。如果每次都重新搜索、读取、筛选，token、时间和工具调用都会被消耗掉。CodeGraph 的思路是先把代码库变成一张本地地图，让 Agent 先问地图，再决定要不要读具体文件。
它主要解决什么痛点
AI 编程工具在小项目里通常还好，文件少，搜索快，读一遍也不贵。但项目一大，常见问题就会出现：
- Agent 为了理解一个模块，反复调用 grep、find、ls、Read。
- 探索子代理读了很多无关文件，主任务上下文却没有变清楚。
- 问一个架构问题时，token 大量花在定位文件上。
- 改一个函数前，不知道谁在调用它、它又调用了谁。
- Web 项目里，URL 路由和实际处理函数之间的关系不够直观。
CodeGraph 试图把这些“先找路”的工作前置。项目索引建好后，Agent 可以直接查询相关符号、调用方、被调用方、影响范围和代码片段。
安装方式
项目提供跨平台安装脚本，不要求用户自己准备 Node.js：
|
|
Windows PowerShell 可以使用：
|
|
如果已经有 Node 环境，也可以直接用 npm：
|
|
或者全局安装：
|
|
安装器会自动检测并配置已安装的 Agent，例如 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent。它会写入对应的 MCP server 配置和指令文件，让这些工具知道什么时候调用 CodeGraph。
初始化项目
安装完成后，需要在目标项目里建立索引：
|
|
这个命令会生成项目级知识图谱索引。README 中提到，只要项目里存在 .codegraph/ 目录，Agent 就可以自动使用 CodeGraph 工具。
如果不想继续使用，也可以卸载全局配置：
|
|
它会移除安装器写入的 MCP server 配置、指令和权限。项目中的 .codegraph/ 索引不会被自动删除，如果要移除项目索引，需要使用 codegraph uninit。
为什么它对 Agent 有用
Claude Code、Codex CLI、Cursor 这类工具在理解代码库时，常常会先做探索：找文件、读入口、查引用、再追调用链。这个过程对人来说像“翻项目”，对模型来说就是一串工具调用和上下文消耗。
CodeGraph 把这一步变成索引查询。Agent 可以先用 codegraph_context 找到相关入口、符号和片段，再用 codegraph_explore 或其他工具读取必要内容。这样做的好处是：
- 少读无关文件。
- 少调用搜索工具。
- 更快找到真正相关的代码。
- 改动前更容易看清影响范围。
- 大型仓库里的架构问题更容易回答。
项目 README 给出的基准测试显示，在 7 个真实开源代码库上，对比启用 CodeGraph 和不启用 CodeGraph，平均结果是成本更低、token 更少、速度更快、工具调用更少。具体数字会受项目规模、语言、问题类型和 Agent 使用方式影响，但方向很清楚：越大的仓库，预索引的价值越明显。
核心能力
1. 智能上下文构建
一个工具调用可以返回入口点、相关符号和代码片段，减少 Agent 先派一堆探索任务再慢慢筛选的情况。对架构理解、模块定位、功能入口分析很有用。
2. 全文搜索
CodeGraph 使用 FTS5 做全文搜索，可以在整个代码库里快速按名称和文本查找代码。这不是替代所有 grep 场景，而是让 Agent 有一个更结构化的第一站。
3. 影响分析
在改函数、类、方法或路由前，可以查询 callers、callees 和影响半径。对重构、修 bug、删除旧代码尤其有用，因为最怕的就是只改了当前文件，却漏掉上游或下游调用。
4. 自动保持新鲜
README 中提到，CodeGraph 使用原生文件系统事件，例如 FSEvents、inotify、ReadDirectoryChangesW，并带有 debounce auto-sync。意思是索引会随着本地代码变化自动更新，不需要每改一个文件都手动重建。
5. 多语言支持
项目列出的支持范围超过 19 种语言，包括 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal / Delphi 等。
这让它更适合多语言仓库和全栈项目，而不是只服务某一种语言。
6. Web 路由感知
CodeGraph 还会识别多种 Web 框架里的路由文件和路由声明，把 URL pattern 和处理函数连接起来。README 中提到的框架包括 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等。
这点很实用。很多 Web 项目的真实入口不是某个明显的 main 函数，而是路由、controller、handler、view 或 resolver。Agent 如果能先知道 URL 到处理函数的关系，理解业务流程会快很多。
本地优先的设计
CodeGraph 强调 100% local。它不需要 API key，不依赖外部服务，索引数据保存在本地 SQLite 数据库里。
对企业项目、私有仓库或敏感代码来说，这个设计很重要。AI 工具接入代码库时，大家最担心的往往不是“能不能查到代码”，而是“代码结构和索引会不会被发出去”。CodeGraph 的定位是本地构建、本地查询、本地服务 Agent。
当然，本地也意味着要考虑磁盘空间、索引时间、文件监听和项目规模。如果仓库特别大，第一次初始化和后续同步仍然需要资源。
适合哪些场景
CodeGraph 更适合这些场景：
- 大型代码库，经常需要问架构和调用链问题。
- 使用 Claude Code、Codex CLI、Cursor 等 Agent 做代码理解和修改。
- 希望减少 Agent 到处读文件、乱搜、反复探索。
- 需要在改动前分析影响范围。
- Web 项目路由复杂，需要快速从 URL 找到处理函数。
- 团队希望给 AI Agent 一个更稳定的本地项目索引。
如果只是几十个文件的小项目，普通搜索已经够快，CodeGraph 的优势可能不明显。它最有价值的地方，是中大型代码库和经常让 Agent 做探索的场景。
使用时要注意什么
第一，CodeGraph 不是替代代码审查和测试的工具。它能帮助 Agent 更快找到相关代码，但不能保证 Agent 的修改一定正确。
第二，索引质量会影响使用效果。项目结构复杂、生成代码很多、语言混杂或 build 产物没有排除时，索引可能会变得臃肿。使用前最好确认 .gitignore、项目目录和索引范围是否合理。
第三，MCP 配置和 Agent 指令很关键。README 里也提醒，CodeGraph 只有在被正确查询时才有帮助。如果 Agent 仍然绕开它去大量读文件，预索引就会变成额外开销。
第四，虽然它是本地工具，也要注意权限。安装器会写入 Agent 配置和权限列表，团队环境中最好统一审查这些配置。
小结
CodeGraph 的价值可以简单理解为：给 AI Agent 一张本地代码地图。它不是让模型更聪明，而是让模型少迷路。
当 Claude Code、Codex CLI、Cursor 这类工具面对大型仓库时，最耗费上下文的往往是探索过程。CodeGraph 用预索引的符号关系、调用图、路由图和全文搜索，把“找代码”这一步提前做好，让 Agent 把更多预算花在理解和修改上。
如果你已经在真实项目里使用 AI 编程工具，并且经常遇到“它读了一堆文件还是没找到重点”的情况，CodeGraph 值得试一下。它代表了 AI 编程工具的一个重要方向：不只是换更强的模型，也要给模型更好的本地代码上下文。
参考资料：