三命令装好 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
CodeGraph 是一款 100% 本地运行的代码知识图谱工具：它把你项目里的符号、调用边和依赖关系预先建好索引，AI Agent 一次查询就能拿到精准上下文。本文带你完成 CodeGraph 安装与项目初始化，共三条命令，不需要 API 密钥，也不需要 Node.js。
它替你省掉了什么
现在 AI Agent 看你的代码，只能靠 grep 加逐文件读取，回答一个架构问题要串起一连串工具调用，把结构硬拼出来。装上 CodeGraph 后，官方在 7 个真实项目上的对比里，工具调用从最多 43 次降到 1~4 次，文件读取直接降到 0。平均下来回答快 53%，token 少 62%。
装之前确认三件事
- 系统与架构：macOS、Linux、Windows 三个平台都覆盖，Intel（x64）和 ARM（arm64）两种架构均有预构建包，安装脚本会自动识别选对版本。
- 运行环境：不用装 Node.js，也不用任何编译工具，发行包内置了运行时；网络能访问下载地址即可。
- 数据去向：索引存放在项目根目录的
.codegraph/里，代码内容不出你的机器。
安装并接入你的 AI 工具
在 macOS / Linux / Windows 上安装 CodeGraph CLI
在终端执行对应命令，下载与你系统匹配的自包含构建：
# 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成功后程序落在~/.codegraph，~/.local/bin里多出一个codegraph启动链接（平台与架构的判定逻辑见安装脚本）。已有 Node.js 的话，npm i -g @colbymchenry/codegraph效果相同。
⚠️ 脚本不会改动当前 Shell 的环境变量。打开一个新终端，运行codegraph version，能打印出版本号（当前为 1.6.0）才算 CLI 装好。
用 codegraph install 接入你的 Agent（MCP 配置）
codegraph install会自动检测机器上已装的 Agent——Claude Code、Cursor、Codex CLI、opencode、Gemini CLI、Kiro、GitHub Copilot 等——并把 MCP 服务器（让 AI 助手调用外部工具的标准协议）写进它们的配置：
codegraph install完成后它会列出每个 Agent 的配置结果，此时重启 Agent，MCP 服务才生效。注意这一步只负责接线，不会索引任何代码。
💡 脚本化或 CI 环境用非交互参数：
codegraph install --yes # 自动检测并全局安装 codegraph install --target=cursor,claude --yes # 指定目标 codegraph install --yes --init # 顺带构建当前项目索引用 codegraph init 为项目建图
进入项目根目录执行初始化，创建.codegraph/目录并构建完整图谱一步完成：
cd your-project codegraph init等索引统计打印完即完成。规模参考：2.7 万文件的 Swift 编译器仓库首次索引约 100 秒，之后单文件保存几秒内自动同步。Agent 检测到项目里有.codegraph/目录，就会自动走 CodeGraph 查询，无需额外设置。
5 分钟验证它真的在工作
先跑 status 检查索引健康度，预期看到文件、符号、边数量以及 journal 模式，应为wal：
codegraph status --json它输出一行 JSON，示意（字段真实，取值随项目变化）：
{"initialized":true,"version":"1.6.0","indexPath":"…/.codegraph","lastIndexed":1751000000000}initialized为true即索引就绪。再问一个真实问题验证效果：
codegraph explore "how does login work"输出是按文件分组的相关源码，外加这些符号之间的调用路径——Agent 在 MCP 里一次拿到的就是同样内容。
✅ 判定标准：status 报出索引、explore 能返回源码与调用路径、编辑文件后等 2 秒再查能看到变化，说明整条链路都在工作。
日常会用到的几个命令
接入之后，高频场景基本靠下面这 5 条覆盖：
| 命令 | 什么时候用 |
|---|---|
codegraph explore <问题> | 改代码前，一次问清某个功能的实现与调用链 |
codegraph impact <符号> | 改动前评估修改这个符号会影响哪些代码 |
codegraph affected src/xx.ts | 改动后找出需要跑的测试文件 |
codegraph upgrade | 一键升级到最新版，--check只查不升 |
codegraph telemetry off | 关闭匿名使用统计，随时可执行 |
完整命令与参数在 CLI 参考 里都有。
踩坑速查
codegraph: command not found—— 安装脚本只写盘、不改当前 Shell → 开一个新终端；macOS/Linux 再确认~/.local/bin在PATH里。
提示 "CodeGraph not initialized"—— 项目根目录还没有.codegraph/→ 在项目里先跑一次codegraph init。
MCP 报database is locked—— 0.9 之前的老版本，或文件系统不支持 WAL（网络盘、WSL2 的/mnt/c常见）→ 先codegraph upgrade；若codegraph status里 Journal 不是wal，把项目挪到本地磁盘。
Windows 与 WSL 共用同一仓库—— 两侧共用一个.codegraph/，跨文件系统边界的 SQLite 锁不可靠 → Windows 侧设CODEGRAPH_DIR=.codegraph-win，各自独立索引，互不干扰。
想反悔也简单：codegraph uninstall会从所有已配置的 Agent 移除设置并删除 CLI（删除前先展示清单），--keep-cli保留 CLI，codegraph uninit只删单个项目的索引。更多场景见故障排查文档。
再深一点
到这里，从装 CLI、接 Agent 到给项目建图的路径就走完了。之后的维护是自动的：原生文件监听捕获每次增删改，2 秒防抖把批量编辑合并成一次同步，Agent 每次连接还会补一次离线期间的对账，索引不会过期。图是怎么解析、符号又是怎么跨文件关联起来的，可以读工作原理；想嵌入到自己的工具里，npm 包还导出了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），仅供参考
