CodeGraph 安装指南：5 分钟让 AI 编程 Agent 少调 88% 工具

CodeGraph 安装指南：5 分钟让 AI 编程 Agent 少调 88% 工具

【免费下载链接】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 为 Claude Code、Cursor、Codex 等 AI 编程 Agent 预建本地代码知识图谱，一次 CodeGraph 安装后，Agent 一次查询即可拿到精准上下文，更少 token、更少工具调用，100% 本地运行、无需 API 密钥。

装完 CodeGraph 能得到什么

官方在 7 个真实开源项目上对比了"有/无图谱"的 Agent 表现（出处：仓库 README 的 Benchmark Results，2026-08 复测）：

机制上：图谱预存了全部符号、调用边与依赖，Agent 不再逐个 grep 和读文件。首次索引方面，2.7 万文件的 Swift 编译器仓库约 100 秒，单文件编辑的重新同步约 4 秒，均出自 README。

平台与架构支持：能否 30 秒判断装得上

所有发行版都是自包含构建，内置 Node 运行时，无需单独安装 Node.js、无需编译。

💡 唯一门槛：网络能访问安装包下载地址。索引数据全部存在项目本地.codegraph/目录（SQLite 数据库），不离开你的机器。

一条命令跑起来的安装命令

安装脚本会自动识别系统与 CPU 架构，下载对应构建。

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命令；macOS/Linux 侧确认~/.local/bin已在PATH中。

接入 AI Agent 与初始化项目

装完 CLI 后要做两件事，各跑一条命令：

• 只接 Agent：运行codegraph install，它会探测本机已装的 Claude Code、Cursor、Codex CLI、opencode、Gemini CLI、Antigravity、Kiro、GitHub Copilot（VS Code / CLI / JetBrains），把 CodeGraph 的 MCP 服务器逐个接入，但不索引任何代码。
• 只建图谱：每个项目运行一次codegraph init，创建本地.codegraph/目录并构建完整图谱，图谱落盘在.codegraph/codegraph.db。

codegraph init

做完如何验证：跑codegraph status能看到索引统计即成功；Agent 检测到项目存在.codegraph/目录后会自动启用 CodeGraph 工具，无需额外设置。

装完后的日常与状态验证命令

• 原生文件监听（macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW）捕获每次文件增删改。
• 防抖窗口（默认 2 秒）把批量编辑合并为一次同步。
• Agent 每次连接时再做一次快速对账，补上离线期间的改动。

也就是说保存文件后几秒内图谱就是最新的，不再需要手动同步。验证状态：

codegraph status # 索引统计与待同步文件 codegraph version # 已安装版本

常用高频命令速查：

遇到问题先查这里

codegraph: command not found—— 原因：安装脚本不改变当前 Shell。解法：开新终端，并确认~/.local/bin在PATH中。

提示 "CodeGraph not initialized"—— 原因：项目还没建索引。解法：进项目目录运行codegraph init。

索引速度慢—— 原因：node_modules、dist等大目录默认已排除，已提交进仓库的 vendored 目录不会自动排除。解法：在codegraph.json的exclude里显式声明，可用--quiet减少输出。

MCP 报database is locked—— 原因：还在用 0.9 之前的旧安装，或文件系统不支持 WAL。解法：按官方脚本重装或npm i -g @colbymchenry/codegraph@latest升级；WSL2 下项目放在/mnt/c等 Windows 盘时移到 Linux 原生文件系统。

WSL2 与 Windows 共用同一仓库—— 原因：SQLite 锁跨系统不可靠。解法：两侧各建独立索引，Windows 侧设环境变量CODEGRAPH_DIR=.codegraph-win。

更多细节见 故障排查文档 与 CLI 参考。

反悔路径：卸载与重置

codegraph uninstall # 完整卸载：移除各 Agent 配置并删除 CLI codegraph uninstall --keep-cli # 只移除 Agent 配置，保留 CLI codegraph uninit # 删除单个项目的 .codegraph/ 索引

总结

装完 CodeGraph 后，工具调用平均减少 88%、文件读取降为零，之后每次让 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