CodeGraph是什么
CodeGraph 是面向 AI 编码代理的预索引代码知识图谱工具，通过 MCP 协议与 Claude Code、Cursor、Codex CLI、OpenCode 及 Hermes Agent 深度集成。利用 tree-sitter 解析代码库，将符号关系、调用图和代码结构存储在本地 SQLite 数据库中，让 AI 代理能通过图谱查询直接定位代码，替代传统的 grep/glob/Read 文件扫描方式。 7 个真实开源项目基准测试验证，CodeGraph 平均可降低 35% 的 API 成本、减少 59% 的 Token 消耗、节省 49% 的时间并减少 70% 的工具调用次数，全程 100% 本地运行，无需外部 API 密钥。
CodeGraph的主要功能
- 预索引代码知识图谱：通过 tree-sitter 将代码库解析为 AST，提取函数、类、方法等符号节点及调用、导入、继承等关系边，构建可即时查询的 SQLite 图谱数据库。
- 智能上下文构建：单次工具调用即可返回入口点、相关符号及代码片段，无需昂贵的探索代理逐文件扫描。
- 全文符号搜索：基于 FTS5 实现跨代码库的符号名称即时搜索，快速定位目标代码。
- 影响半径分析：追踪任意符号的调用者（callers）、被调用者（callees）及完整影响范围，在修改前评估波及面。
- 框架感知路由：自动识别 14 种 Web 框架的路由文件，将 URL 模式与对应的处理器函数/类关联。
- 实时自动同步：通过原生 OS 文件事件（FSEvents/inotify/ReadDirectoryChangesW）监听项目变更，2 秒防抖后自动增量同步图谱。
- 变更影响测试追踪：
codegraph affected命令可追踪变更文件的传递依赖，精准定位受影响的测试文件，适用于 CI 流水线。 - 零配置即开即用：自动根据文件扩展名识别语言，自动尊重
.gitignore规则，无需编写任何配置文件。
如何使用CodeGraph
- 安装 CodeGraph：在终端执行
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh（macOS/Linux）或irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex（Windows PowerShell）；已安装 Node.js 的用户也可直接运行npx @colbymchenry/codegraph - 选择集成代理：安装器自动检测系统中已安装的 AI 代理（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent），交互式提示选择要配置的代理并自动写入 MCP 配置
- 重启 AI 代理：完成安装后重启对应的 AI 代理，使 MCP 服务器配置生效
- 初始化项目索引：进入项目目录执行
codegraph init -i，构建该项目的知识图谱索引；同时会自动配置项目级代理规则文件（如.cursor/rules/codegraph.mdc） - 开始使用：当项目目录中存在
.codegraph/文件夹时，AI 代理会自动调用 CodeGraph 工具进行代码查询与探索；也可通过 CLI 执行codegraph query <关键词>、codegraph callers <符号名>等命令手动查询
CodeGraph的核心优势
- 显著降低使用成本：经 7 个真实开源项目（VS Code、Excalidraw、Django、Tokio、OkHttp、Gin、Alamofire）测试，平均节省 35% API 成本、59% Token 消耗、49% 执行时间、70% 工具调用次数；大型仓库效果尤为明显。
- 100% 本地隐私安全：所有数据存储于本地 SQLite 数据库，无需联网、无需 API 密钥、无数据上传，完全保障代码隐私。
- 跨平台自包含运行：为 Windows（x64/arm64）、macOS（x64/arm64）、Linux（x64/arm64）提供独立构建包，自带 Node 运行时，无需本地编译或额外安装 Node.js。
- 19+ 语言全覆盖：完整支持 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Svelte、Vue、Liquid、Pascal/Delphi、Lua、Luau 等主流及小众语言。
- 深度框架集成：原生识别 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、React Router、SvelteKit 等 14 种框架的路由语法，将 URL 与处理器精准关联。
- 无缝 Agent 集成：通过 MCP 协议与主流 AI 编码代理对接，安装器自动完成配置，无需手动编辑 JSON 配置文件。
CodeGraph的项目地址
- GitHub仓库：https://github.com/colbymchenry/codegraph
CodeGraph的应用场景
- 架构问题快速解答：向 AI 代理询问”扩展宿主进程如何与主进程通信？”等架构级问题，代理通过图谱直接定位相关源码，无需发散式文件扫描。
- 代码审查与影响分析：在修改核心函数前，通过
codegraph_impact分析变更的波及范围，避免引入回归问题。 - 新人上手与代码熟悉：新团队成员通过自然语言向 AI 代理提问，快速理解项目结构、模块依赖及关键业务逻辑。
- 精准测试定位：在 CI 流水线中结合
git diff与codegraph affected，仅运行受代码变更影响的测试文件，缩短构建时间。 - 跨文件重构辅助：重构公共 API 时，利用 callers/callees 追踪全库引用点，确保所有调用处同步更新。