CodeGraph 安装部署指南：给 AI 编码助手装上本地代码知识图谱
【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph
AI 编程助手理解代码的传统方式是 grep 加逐个读文件——慢、费 token、还容易漏掉跨文件的调用链。CodeGraph 的做法是把这件事反过来：它预先扫描整个仓库，把每个符号、调用边和依赖关系存进一个本地 SQLite 知识图谱，助手一次查询就能拿到相关源码、调用路径和影响范围。官方在 7 个真实开源项目上的对照实测里，工具调用次数平均减少 88%，token 消耗少 62%，七个项目的文件读取次数全部降为零。
整个过程只有三件事要亲手做：装 CLI、接入 Agent、在项目里初始化一次。装完之后索引会随文件保存自动更新，不需要再维护。
无需 Node.js 的一行安装：macOS、Linux 与 Windows PowerShell 都适用
所有发布版本都是自包含构建，内置了 Node 运行时，不需要机器上装 Node.js，也不需要本地编译。脚本会自动识别操作系统和 CPU 架构（x64 / arm64），下载对应的构建。
| 平台 | 架构 | 安装方式 |
|---|---|---|
| macOS | x64 / arm64 | 一行安装命令 或 npm |
| Linux | x64 / arm64 | 一行安装命令 或 npm |
| Windows | x64 / arm64 | PowerShell 一行安装命令 或 npm |
最省事的方式是不分平台的一行命令，它会自动下载运行环境并完成安装：
npx @colbymchenry/codegraph机器上已经有 Node.js 的话，npm 全局安装同样可用：
npm i -g @colbymchenry/codegraph更习惯脚本的读者可以直接跑项目仓库里的install.sh（macOS / Linux）或install.ps1（Windows PowerShell），二者逻辑一致：把程序装到~/.codegraph，并在~/.local/bin创建codegraph启动链接。
两点说明：
- 安装脚本不会修改当前 Shell 的环境变量，跑完后请打开一个新终端再执行后续命令，否则找不到
codegraph。 - 索引数据全部保存在项目目录下的
.codegraph/里，不离开本机，也不需要任何 API 密钥。
把 CodeGraph 接进 Claude Code、Cursor 或 Copilot
新终端里运行安装器：
codegraph install它会探测机器上已安装的 Agent 并逐个写入 MCP 服务器配置，覆盖：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，以及 GitHub Copilot（VS Code / Copilot CLI / JetBrains IDE 三种形态）。注意这一步只负责"接线"，不会索引任何代码——构建图谱是下面codegraph init的事。装一次是全局生效的，所有项目共用，不用每个项目重跑。
脚本化或 CI 场景下可以加参数跳过交互：codegraph install --yes自动检测并全局安装；codegraph install --target=cursor,claude --yes指定目标；codegraph install --yes --init顺手把当前项目也初始化了。各参数含义见 CLI 参考。
配置写好后重启一次 Agent，让 MCP 服务加载生效。
用 codegraph init 给项目建图，之后文件保存即自动同步
进入项目目录，运行：
codegraph init这条命令一步做完两件事：创建本地.codegraph/目录 + 构建完整代码图谱。官方给出的量级参考：2.7 万文件的 Swift 编译器仓库首次索引约 100 秒；建好之后单文件编辑的增量重新同步约 4 秒。
图谱建好后，Agent 检测到项目里存在.codegraph/目录就会自动改用 CodeGraph 工具，无需额外设置。
自动同步默认开启，机制分三层：
- 原生文件监听（macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW）捕获每次文件增删改；
- 防抖窗口（默认 2 秒）把连续编辑合并成一次增量同步；
- Agent 每次连接 MCP 服务器时会做一次快速对账，补上离线期间的改动——比如你在终端
git pull或换了个编辑器改代码。
换句话说，你保存文件后的几秒内图谱就是新的。想确认状态随时可以跑codegraph status，有待同步文件时会列出清单。
装完之后的日常：高频命令速查与状态检查
真正日常用到的命令不多，收在一张表里：
| 命令 | 用途 |
|---|---|
codegraph explore <问题> | 一次返回相关源码 + 调用路径 + 影响范围 |
codegraph impact <符号> | 改动前分析受影响的代码 |
codegraph affected src/xx.ts | 找出受改动的测试文件 |
codegraph status | 查看索引统计与待同步文件 |
codegraph sync | 手动增量同步（监听被禁用时的兜底） |
codegraph upgrade | 一键升级到最新版本 |
codegraph version | 查看已安装版本 |
codegraph telemetry off | 关闭匿名使用统计（也可用DO_NOT_TRACK=1） |
完整命令与参数列表见 CLI 参考，explore/impact/affected这类查询命令的详细说明在 Getting Started 系列文档里也有覆盖。
遇到问题时
codegraph: command not found—— 安装脚本不改变当前 Shell，打开新终端；同时确认~/.local/bin在PATH中（macOS / Linux）。- 提示 "CodeGraph not initialized"—— 项目里还没建图，先在该目录跑
codegraph init。 - 索引速度慢——
node_modules、dist等大目录默认已排除，检查是否被意外包含进索引；加--quiet可减少输出开销。 - MCP 报
database is locked—— 0.9 之前的旧版没有内置运行时，重装即可；若codegraph status里Journal:不是wal，说明当前文件系统开不了 WAL（常见于网络盘和 WSL2 的/mnt分区），把项目连同.codegraph/移到本地磁盘。 - WSL2 与 Windows 共用一个仓库—— 不要两侧共用同一个
.codegraph/，给 Windows 侧设环境变量CODEGRAPH_DIR=.codegraph-win，让两边各自维护独立索引。
更多场景的修复方法见 故障排查文档。
想反悔怎么办
卸载也是一条命令的事，执行前会先展示将被移除的清单：
codegraph uninstall # 从所有已配置的 Agent 移除配置，并删除 CLI 本体 codegraph uninstall --keep-cli # 只移除 Agent 配置，保留 CLI codegraph uninit # 删除单个项目的 .codegraph/ 索引延伸阅读
装好之后想弄明白图谱内部怎么运转，项目文档里有现成的：工作原理讲提取、存储、解析和自动同步四个阶段；知识图谱概念列出了节点和边的完整类型词汇；索引指南覆盖了大仓库的调优细节。
【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)