CodeGraph安装指南：三平台一键部署与 Agent 快速接入-平芜编程栈

CodeGraph安装指南：三平台一键部署与 Agent 快速接入

【免费下载链接】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

你让 Claude Code 帮你追一条跨文件的调用链，它开始 grep、再读一个文件、再 grep——十几轮工具调用过去，token 账单先跳了，上下文还可能拿不准。CodeGraph 解决的就是这件事：一次安装，把整个仓库的符号、调用边和依赖关系预先建成本地代码知识图谱，Agent 一次查询就能拿到精准上下文，并且 100% 本地运行、不需要任何 API 密钥。

接入之后，一次回答能省多少

先说结论：官方在 7 个真实开源项目上的实测里，接入 CodeGraph 后速度、token、成本、调用量四项全面下降，文件读取直接归零。

维度	不用 CodeGraph	接入 CodeGraph 后
回答速度	基线	平均快 53%
Token 消耗	基线	少 62%
单题成本	基线	平均省 44%
工具调用次数	最多 43 次	减少 88%
文件读取次数	最多 19 个文件	0 次

除了省，还有两个附带收益：图谱随代码改动自动同步，索引不会过期；所有数据留在本机.codegraph/目录，不离开你的机器。

先确认机器条件：自包含构建，三平台通用

所有发行版都是自包含构建——内置 Node 运行时，不用装 Node.js、不用编译。你只需要网络能访问安装包下载地址。

平台	架构	安装路线
macOS	x64 / arm64	Shell 脚本或 npm
Linux	x64 / arm64	Shell 脚本或 npm
Windows	x64 / arm64	PowerShell 脚本或 npm

把 CLI 装到本机：脚本或 npm 二选一

两条路线结果一样，装完都能直接敲codegraph。

路线一：一键安装脚本。脚本会自动识别操作系统和 CPU 架构、下载对应构建，把程序装进~/.codegraph，并在~/.local/bin创建codegraph启动链接：

# macOS / Linux（Terminal） 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.js 的话，走 npm 更简单，等价于装一个自包含的全局包：

npm i -g @colbymchenry/codegraph

⚠️ 两条路线都不会修改当前 Shell 的环境变量。装完请打开一个新终端再继续，否则找不到codegraph命令。

接入 Agent 并给项目建图

CLI 装好只是第一步，真正让 Agent"用上"图谱要两件事：把 MCP 服务接进 Agent，再给项目建一次图。

在新终端里运行安装器，它会自动检测本机在用的 Agent 并逐个写入 MCP 配置——支持 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，以及 GitHub Copilot（VS Code / Copilot CLI / JetBrains IDE），完成后重启 Agent 即生效：

codegraph install

在脚本化或 CI 场景下可以加参数跳过交互：

codegraph install --yes # 自动检测，全局安装 codegraph install --target=cursor,claude --yes # 只配置指定目标 codegraph install --yes --init # 顺带初始化当前项目

接着回到你自己的项目目录跑一次codegraph init，它会创建本地.codegraph/目录并同步构建完整图谱——一条命令两件事。量级参考：数万文件的 Swift 编译器仓库首次索引约 100 秒。此后 Agent 每次进入项目发现.codegraph/存在就会自动改用 CodeGraph 工具，不再需要你做任何设置。

装完怎么确认：两条状态命令

索引构建完成后，用下面两条命令确认一切就绪——status看索引统计和待同步文件，version看已安装版本：

codegraph status codegraph version

💡 反悔也简单：codegraph uninstall会从所有已配置的 Agent 中移除配置并删除 CLI 本体（删除前先展示清单）；codegraph uninstall --keep-cli只移除 Agent 配置；单个项目的索引用codegraph uninit删。

文件改了，图谱自己跟着变

自动同步默认开启，不需要任何配置。它的逻辑分三层：底层用原生文件监听（macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW）捕获每一次文件增删改；中间用一个默认 2 秒的防抖窗口，把连续批量编辑合并成一次同步；最后，Agent 每次连接时还会做一次快速对账，把离线期间漏掉的改动补上。

环节	它在做什么
捕获	原生文件监听盯着每次文件增删改
合并	2 秒防抖窗口把批量编辑合成一次同步
对账	Agent 连接时快速核对，补上离线改动

也就是说，你或 Agent 保存文件后几秒内图谱就是最新的，从此没有"手动同步"这个概念。单文件编辑后的重新同步实测约 4 秒。

日常高频命令速查

装好后你最高频接触的就是这几条：

命令	作用
`codegraph explore <问题>`	一次返回相关源码 + 调用路径 + 影响范围
`codegraph impact <符号>`	改动前分析受影响的代码
`codegraph affected src/xx.ts`	找出受本次改动影响的测试文件
`codegraph upgrade`	一键升级到最新版本
`codegraph telemetry off`	关闭匿名使用统计（也支持环境变量`DO_NOT_TRACK=1`）

三个最常见的故障，按现象排查

现象：codegraph: command not found。原因：安装脚本不会改动当前 Shell 的PATH，你多半还停在旧终端。解决：打开一个新终端再试；仍不行就确认~/.local/bin已在PATH中。

现象：提示 "CodeGraph not initialized"。原因：当前项目还没有.codegraph/目录，图谱没建。解决：在项目根目录跑一次codegraph init。

现象：MCP 报 database is locked。原因：0.9 之前的老版本没有内置运行时，需要重装获取新版本；WSL2 中项目放在/mnt/c等 Windows 盘上也会加重锁竞争。解决：重装最新版；把项目移到 Linux 原生文件系统。WSL2 与 Windows 共用同一仓库时，给 Windows 侧设置环境变量CODEGRAPH_DIR=.codegraph-win，让双方各建独立索引避免冲突。