colbymchenry/codegraph
AI 工程为 AI 编程 Agent 建立本地代码知识图谱,一次查询返回符号源码、调用链和改动影响范围。
项目介绍
CodeGraph 把代码库解析成一份本地 SQLite 知识图谱,记录符号、调用边、导入、继承关系和框架路由,再通过 MCP 服务器提供给 AI 编程 Agent。当 Agent 需要回答「X 怎么工作」「改 Y 会影响什么」这类结构性问题时,不必再逐个文件 grep、Read、手工拼调用链,只需调用一次 codegraph_explore,就能拿到按文件分组的原始源码、符号之间的调用路径和影响范围摘要。索引完全在本地,文件变化后自动同步。
它面向已经在用 Claude Code、Cursor、Codex CLI、opencode、Gemini CLI、Copilot、Windsurf、Kiro 等工具的开发者,尤其是中大型、多语言代码库——在这些项目里,逐文件探索会消耗大量工具调用和 token。解析由原生 Rust 内核完成,内置 tree-sitter 语法,覆盖 20 多种语言,并能识别 20 多个 Web 框架的路由,包括 Expo Router 与 Next.js 的导航边,以及 iOS 与 React Native 之间的桥接。
快速使用
官方流程分三步:装 CLI、接入 Agent、初始化项目。
- 安装 CLI。安装器自带 Node 运行时,不需要预先安装 Node.js:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows(PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
已有 Node 也可以改用 npm i -g @colbymchenry/codegraph。安装器不会修改当前 shell,装完需要新开一个终端。
-
接入 Agent。在新终端运行
codegraph install,它会自动检测已安装的 Agent,把 CodeGraph 的 MCP 服务器配置写进去,并在CLAUDE.md、AGENTS.md等说明文件里补一段简短用法。这一步只配置 Agent,不索引代码。 -
初始化项目:
cd your-project
codegraph init
该命令创建 .codegraph/ 目录并构建图谱,默认开启自动同步,之后改文件不需要手动重跑。接入完成后重启一次 Agent,在已有索引的项目里它会自动调用 CodeGraph。
配置与数据处理
语言按文件扩展名自动识别,不需要按语言单独配置。默认跳过 node_modules、dist、vendor、.venv 等依赖和构建目录,也会遵循 .gitignore;大于 1 MB 的文件不入图。已提交进仓库但不想索引的目录,可以在项目根目录的 codegraph.json 里用 exclude 排除;.dota_lua 这类非标准扩展名则用同一文件的 extensions 映射到受支持的语言。
索引存放在每个项目的 .codegraph/ 目录中,工具本身不会把它推送出去,但会不会进版本库取决于你的 .gitignore;codegraph init --local-only 可以确保它不进 git。作为库嵌入时需要 Node 22.5+(依赖内置 node:sqlite),CLI 和 MCP 服务器使用打包的运行时,不受此限制。匿名使用统计默认开启,可用 codegraph telemetry off、CODEGRAPH_TELEMETRY=0 或 DO_NOT_TRACK=1 关闭。项目采用 MIT 许可证,支持 Windows、macOS 和 Linux 的 x64 与 arm64 平台 Get Started。
HotRepo 点评
从 2026-05-18 到 2026-05-26 的日榜快照里,仓库从 3,855 星涨到 26,683 星,单日新增在 1,869 到 4,294 之间;到 2026-10 的快照已在 72k 星以上,2026-11-18 还在 TypeScript 日榜上拿到第 10 名。对于一个目标是「省掉 Agent 工具调用」的项目,这样的体量并不常见。
更值得细看的是 README 里的基准测试:88% 更少的工具调用、62% 更少的 token,是在七个开源仓库上用 Claude Opus 4.8 测出来的,并且测试框架在两组实验中都刻意屏蔽了 CLI。这个测量很窄——每个仓库只问一个架构问题,取四次运行的中位数——也不能说明图谱在类型松散、动态性强的代码上是否同样有效。自报的跨文件覆盖率(本仓库 95.8%、requests 100%)反而更能说明图谱效用的边界。Hacker News 上的讨论不多,其中一条回复把它定性为「包在文件系统 I/O 外面的 AST 层」,而不是解决上下文持久化 HN 讨论;这个说法是公允的:CodeGraph 减少的是探索工作,不是模型的上下文上限。
对拥有大型多语言仓库、并且已经配好编程 Agent 的团队来说,接入成本不高——一次安装器、每个项目一次 init。在依赖它之前,值得确认的是你的技术栈在语言覆盖范围内、自动同步在超大仓库上跟不跟得上,以及遥测默认开启这一点。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。
Hacker News 讨论
相关推荐
- xingkongliang/skills-manager给同时使用多个编程 Agent 的人,集中存放、分发并同步 skills 的桌面工具。
- Alishahryar1/free-claude-code把已有的编程 Agent 和 IDE 接到统一模型源,支持免费额度和备用模型切换。
- ScottDuncanAI/PID-to-Knowledge-Graph把 P&ID/PFD PDF 转成可查询的流程图谱,记录工艺流向、仪表位置和控制回路,面向工艺工程人员。
- Graphify-Labs/graphify把代码库解析成可查询的知识图谱,让编程 Agent 沿着图找答案而不是满仓库 grep。
- abhigyanpatwari/GitNexus把代码库索引成可查询的知识图谱,让编程 Agent 和编辑器通过 MCP 查找调用、依赖和影响范围。