5 分钟装好 CodeGraph 并接入 AI 助手：完整指南-开发者社区

5 分钟装好 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 的做法相反：先把整个仓库的符号、调用边、依赖关系建成语义级知识图谱，AI 助手查一次图谱就能拿到精准上下文，而不再自己翻文件。

30 秒速览：装完能得到什么

一次安装，所有助手受益：Claude Code、Cursor、Codex、opencode、Gemini、GitHub Copilot 等 9 类助手自动接上同一个 MCP 服务。
纯本地运行：无需 API 密钥，无需外部服务，索引全部落在项目里的.codegraph/目录。
零配置免 Node：安装包自带运行时，不编译、不装依赖。
装完基本不用管：文件一改，图谱自动同步，不存在"索引过期"。
耗时：CLI 安装 + 助手接入约 2 分钟；单个项目首次建图视仓库大小，量级见下文。

官方在 7 个真实开源仓库上的实测均值（数据来自 README 的 2026-08 复测）：

指标	无 CodeGraph	有 CodeGraph
工具调用次数	最多 43 次	少 88%
Token 消耗	基线	少 62%
回答耗时	基线	平均快 53%
成本	基线	平均省 44%
文件读取次数	最多 19 个文件	7 个仓库全部 0 次

选一条安装路线：脚本还是 npm

所有发行版都是自包含构建（内置 Node 运行时），三大平台 x64 与 arm64 全覆盖：

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

选择建议：机器上没有 Node、或者不想污染全局环境，走一键脚本；已经有 Node 且习惯npm i -g管理工具，走 npm 路线，两条路装出来功能一致。

动手 · 把 CLI 跑起来

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？用 npm 装（对版本无要求）：

npm i -g @colbymchenry/codegraph

脚本会把程序装到~/.codegraph，并在~/.local/bin创建codegraph启动链接。

⚠️ 安装脚本不会修改当前 Shell 的环境变量。打开一个新终端再执行下一步，否则找不到codegraph命令。

新终端里跑这条，输出版本号（如1.6.0）即为安装成功：

codegraph version

接上你的 AI 助手：一条命令配置 MCP

codegraph install

安装器会自动检测并写入各助手的 MCP 配置：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，以及 GitHub Copilot（VS Code / Copilot CLI / JetBrains IDE），并顺带在对应助手的说明文件里写入 CodeGraph 小节。这一步只接助手、不建索引，接完重启你的 Agent让 MCP 服务生效。

CI 或脚本化场景可用非交互参数：

codegraph install --yes # 自动检测，全局安装 codegraph install --target=cursor,claude --yes # 指定目标 codegraph install --print-config codex # 只打印配置片段，不写文件

让项目被读懂：每个项目初始化一次

cd your-project codegraph init

codegraph init一步完成两件事：创建本地.codegraph/目录 + 构建完整代码图谱。量级参考（官方实测）：2.7 万文件的 Swift 编译器仓库首次建图约 100 秒；建好之后，单文件编辑的再同步约 4 秒，日常保存触发的同步通常在 1 秒以内。

全局的codegraph install覆盖所有项目，codegraph init每个项目跑一次即可。Agent 检测到项目里存在.codegraph/目录就会自动使用 CodeGraph 工具，无需额外设置。

验收清单：确认装对了

✅codegraph version输出版本号
✅ 项目根目录生成了.codegraph/目录
✅codegraph status显示索引统计，且 Journal 模式为wal
✅ 重启 Agent 后，MCP 工具中出现codegraph_explore等工具
✅ 随便问 Agent 一个跨文件调用链问题，它直接查图谱回答，不再逐个读文件

日常与进阶：高频命令速查

命令	用途
`codegraph explore <问题>`	一次返回相关源码 + 调用路径 + 影响范围
`codegraph impact <符号>`	改动前分析受影响代码
`codegraph affected src/xx.ts`	找出受改动的测试文件
`codegraph sync`	手动增量同步（正常情况不需要）
`codegraph status`	查看索引统计与待同步文件
`codegraph upgrade`	一键升级到最新版（`--check`仅检查）
`codegraph telemetry off`	关闭匿名使用统计

自动同步默认开启，机制是三层：原生文件监听（macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW）捕获每次增删改；防抖窗口（默认 2 秒，可用CODEGRAPH_WATCH_DEBOUNCE_MS调整）把批量编辑合并成一次同步；Agent 每次重连时再做一次快速对账，补上离线期间的改动。防抖窗口内若文件未入索引，MCP 响应会带陈旧文件横幅提示 Agent 直接读文件兜底——所以装完你只需要知道一件事：图谱自己跟着代码走。

卡住了 · 对症下药

现象	原因	解法
`codegraph: command not found`	安装脚本不改变当前 Shell	打开新终端；确认`~/.local/bin`在`PATH`中
提示 "CodeGraph not initialized"	项目没跑过初始化	项目目录里执行`codegraph init`
索引速度慢	大目录未被排除、输出开销	`node_modules`/`dist`默认已排除；`codegraph index --quiet`减少输出
MCP 报`database is locked`	0.9 之前老版本，或文件系统不支持 WAL（网络盘、WSL2`/mnt`）	重装获取内置运行时；把项目连同`.codegraph/`移到本地磁盘
MCP 报`Transport closed`（WSL2，项目在`/mnt/c`）	跨 OS 边界的本地 socket 不可靠	环境变量设`CODEGRAPH_NO_DAEMON=1`走进程内服务，或把项目移到 Linux 原生文件系统
Windows 与 WSL 共用一个仓库	两边锁冲突	Windows 侧设`CODEGRAPH_DIR=.codegraph-win`，各自独立索引