CodeGraph 安装实战指南：三条命令接入你的 AI Agent-开发者社区

CodeGraph 安装实战指南：三条命令接入你的 AI 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

CodeGraph 是一款面向 AI 编程 Agent 的 100% 本地代码知识图谱：把整个仓库的符号、调用关系预先索引成图，Agent 不再需要逐个文件 grep。CodeGraph 安装流程只有三条命令——装 CLI、接入 Agent、初始化项目；装好后你向 Agent 问代码，它一次查询就能拿到源码、调用路径和影响范围。

开工前核对：四件事先确认

平台：macOS（Intel 与 Apple Silicon）、Linux、Windows 均支持 x64 / arm64，发行版都是自包含构建
环境：不用装 Node.js、不用编译，只需网络能访问下载地址；若偏好 npm 方式，则需要一个 Node 环境
数据：索引全部落在项目的.codegraph/目录里，不会离开你的机器，也不需要任何 API 密钥
语言：TypeScript、Python、Go、Rust、Java、C/C++ 等 30+ 语言开箱即用，无需逐语言配置

🚀 快速上手：三条命令接入 Agent

先装 CLI，这一步只有第一条命令因平台而异。

macOS / Linux 一行安装

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

脚本自动识别系统与架构，把对应构建下载进~/.codegraph，并在~/.local/bin建好codegraph启动链接（细节见 install.sh）。

Windows 一行安装（PowerShell）

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

逻辑与 Shell 脚本一致，程序解到%LOCALAPPDATA%\codegraph，并把它的bin目录追加进用户 PATH（见 install.ps1）。

用 npm 装

npm i -g @colbymchenry/codegraph

与上面两条等效，CLI 自带运行时，两种方式都不涉及编译。注意：安装脚本不会改动当前 shell 的环境变量，先打开一个新终端再执行下一步，否则找不到codegraph命令。

新终端里，任何平台都是同样三条命令：

# 自动检测并写入你正在用的 Agent 的 MCP 配置 codegraph install # 进入项目，创建 .codegraph/ 并构建完整图谱 cd your-project codegraph init # 可选：查看索引统计与待同步文件 codegraph status

codegraph install跑完记得重启你的 Agent，MCP 服务才会加载；init每个项目跑一次，而install全局装一次就覆盖所有项目。想图省事还有捷径：npx @colbymchenry/codegraph会下载并直接跑安装器；CI 里则用codegraph install --yes --init免交互一次完成。

安装到底改了什么

花半分钟看看幕后发生了什么，知道东西写在哪，以后排障就快一半。

安装脚本写了什么

macOS/Linux 脚本把构建包放进~/.codegraph/versions/<version>，维护一个current软链，~/.local/bin的启动链接指向它；Windows 脚本解包到%LOCALAPPDATA%\codegraph\current，并把bin目录写进用户 PATH。两个脚本还会沿 PATH 找有没有别的codegraph副本（最常见的是 npm 全局装的旧版本），找到就警告它会抢先被执行。

codegraph install 写了什么

它给每个 Agent 逐个接上 CodeGraph 的 MCP 服务器，覆盖 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro 和 GitHub Copilot（VS Code / Copilot CLI / JetBrains）。以 Claude Code 为例：MCP 条目写进~/.claude.json（全局）或项目里的.mcp.json（本地），权限写进settings.json，CLAUDE.md追加一小段带标记的说明；其他 Agent 写各自的说明文件，Cursor、Kiro 只写 MCP 配置。这一步只"接线"，不索引代码。

init 在项目里生成了什么

项目根目录多出.codegraph/，核心是codegraph.db——一个本地 SQLite 库，存着符号、调用边、依赖和全文索引。这个目录一旦出现，Agent 会自动启用 CodeGraph 工具，无需额外配置。之后的文件改动由原生文件监听（macOS FSEvents、Linux inotify、Windows ReadDirectoryChangesW）捕获，经 2 秒防抖合并后增量同步；Agent 每次连接时还会做一次快速对账，补上离线期间的改动。

🔍 坑与自救

codegraph: command not found→ 安装脚本不改动当前 shell → 打开新终端；仍不行就确认~/.local/bin在 PATH 中
版本号对不上刚装的→ PATH 里靠前有个同名旧副本（通常是 npm 全局装）被抢先执行 →npm rm -g @colbymchenry/codegraph，或把新路径排在 PATH 前面
MCP 提示 "CodeGraph not initialized"→ 项目还没建索引 → 在项目目录跑一次codegraph init
database is locked→ 0.9 之前的老安装，或文件系统不支持 WAL（WSL2 的/mntWindows 盘常见）→ 重装最新版，确认codegraph status里Journal:显示wal；不是的话把项目挪到本地盘
WSL2 中工具调用报Transport closed→ Windows 盘上共享后台服务不可靠 → 设CODEGRAPH_NO_DAEMON=1，或把项目挪到~/等 Linux 原生路径
Windows 与 WSL 共用一个仓库→ 两侧锁会互相冲突 → Windows 侧设CODEGRAPH_DIR=.codegraph-win各建各的索引，程序会自动跳过对方的目录

日常与退场

codegraph explore "登录流程是怎么走的"—— 一次返回相关源码、调用路径与影响范围
codegraph impact <符号>/codegraph affected src/xx.ts—— 改前查波及面，改后找受影响的测试
codegraph status—— 随时查看索引统计与待同步文件
codegraph upgrade—— 一键升级，自动识别你当初的安装方式（bundle / npm / npx）；--check只查询不升级
codegraph telemetry off—— 关闭匿名使用统计（安装器会先询问；设DO_NOT_TRACK=1同样有效）
codegraph uninstall—— 从所有已配置的 Agent 和 CLI 本体一并移除，删除前先展示清单；--keep-cli只拆 Agent 配置；codegraph uninit删掉单个项目的索引