一、grep 解决不了的问题:只认「字」,不认「路」
让 Claude Code 或 Codex 改一个稍大点的项目,它常常满屏 grep、反复打开文件、读了又读。这就像一个刚到陌生城市的人,没有地图,只能挨条街走过去问路:慢、费劲,还容易走错。
codegraph 做的事,就是先把你的代码库测绘成一张地图,再交给 AI 这位「副驾驶」当导航用。函数、类、变量是一个个地点,调用关系是连接它们的道路。
按官方实测,接上之后平均约省 25% 成本、少用 57% token、快 23%,并减少 62% 的工具调用。
| 问题 | 用什么 |
|---|---|
| 哪行日志里写了 connection timeout | grep / 全文搜索 |
| getUser 定义在哪 | codegraph |
| 谁调用了 getUser | codegraph |
| 改了 getUser 会影响什么 | codegraph |
二、它不是语义搜索,却能帮 Claude 精准找代码
codegraph 听不懂「登录逻辑」这种人话,第一跳由模型把自然语言映射到 login、auth、getUser 等符号名。
第二跳交给 codegraph:拿到符号名后,谁调用它、它调用谁、改动会波及哪里,这些机械而精确的遍历一次就能返回。
所以 codegraph 是 AI 的结构导航仪,不碰模型的语义理解,只替掉 grep 加反复读文件这个又笨又贵的环节。
三、2 分钟拿到第一张地图
安装 CLI 后,运行 codegraph install 将它注册成 MCP 服务,再在项目目录建立初始索引。第一次索引完成后,Claude Code 和 Codex 就能调用地图。
# 安装并接入 CLI
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install
cd 你的项目
codegraph init -i
codegraph status四、地图会不会过期:三层刷新机制
刚改完代码,CodeGraph 的图谱能及时同步嘛?
CodeGraph 是会刷新的离线快照,从最重到最轻依次是全量重建、自动监听、Git 钩子兜底。监听器有约 2 秒防抖窗口,连续保存时会顺延。
- 第一次初始化或怀疑地图损坏:使用 codegraph init 或 index --force。
- 日常写代码:打开 MCP 服务后由监听器自动增量同步,无需手敲命令。
- WSL 或监听失灵:在 post-commit 中执行 codegraph sync --quiet 兜底。
五、地图也有画不出的地方:三类失效场景
地图给出不准的结果,通常只有三类来源:
- 时效滞后:快照还没有追上最新改动。
- 未初始化:项目没有建立过快照,需要先执行 codegraph init -i。
- 结构盲区:它理解静态结构,但不理解登录这类语义,也无法完全推断运行时反射。
六、副驾驶拿到了哪些工具
安装完成后,AI 可以通过 MCP 调用 explore、search、callers、callees、impact、node、files 和 status。日常优先使用 explore,一次拿到源码、调用流和影响面。
| 工具 | 用途 |
|---|---|
| codegraph_explore | 首选入口:源码 + 调用流 + 影响半径 |
| codegraph_search | 按名字找符号 |
| codegraph_callers / callees | 谁调用 X / X 调用谁 |
| codegraph_impact | 改 X 会影响什么 |
| codegraph_files | 查看项目文件结构 |
七、codegraph vs fast-context vs Auggie MCP
三者解决的不是同一类问题:codegraph 擅长本地结构和影响面,fast-context 擅长联网语义检索,Auggie 适合超大代码库的商业语义引擎。它们可以并存,按问题类型选择即可。
| 维度 | codegraph | fast-context | Auggie |
|---|---|---|---|
| 机制 | Tree-sitter → AST 图谱 | 模型现场语义检索 | Context Engine |
| 数据位置 | 纯本地 SQLite | 需要联网 | 商业云端 |
| 成本 | 免费开源 | 按服务配置 | 商业付费 |
小结
它是 AI 的结构导航仪:把代码解析成知识图谱,回答谁调用谁、改了影响谁。日常用 codegraph_explore,结构问题选 codegraph,语义检索再搭配 fast-context 或 Auggie。