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本文以 CodeGraph 的 Quickstart 文档为主线完整还原安装 CLI → 接入 Agent → 初始化项目这条最短可用路径并结合仓库中 install.sh、install.ps1、CLI 入口 与 安装器编排逻辑 的源码解释每个步骤背后的实际行为、可复现的可选参数以及codegraph install为何只接 Agent、不索引代码、codegraph init为何一步建图。读完你可以独立完成从零到 Agent 自动调用 CodeGraph 工具的本地部署并能自行排查 PATH 冲突、目标 Agent 未识别、非交互式安装等常见问题。1. 安装 CLI一行命令无需 Node.jsQuickstart 的第一步是安装 CLI。CodeGraph 的官方分发方式是自包含 bundle——它把一份内嵌vendored的 Node 运行时和应用代码一起打包因此目标机器不需要预先安装 Node.js、构建工具或 npm适合在一台干净的 Linux VPS 上通过 SSH 直接部署。官方文档给出的两条一键命令如下# 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 | iex1.1 安装脚本到底做了什么逐行看 install.sh 可以确认这条命令完成的事情比下载一个二进制要多。它的执行顺序是平台探测通过uname -s/uname -m把系统映射成darwin/linux与arm64/x64组合成目标三元组如linux-arm64。不支持的平台或架构会直接报错退出。版本解析默认取 latest。脚本优先读取 GitHubreleases/latest的Web重定向而非调用 GitHub API来解析版本因为未认证的 API 有每小时 60 次的限流在共享主机 / CI 上很容易触发 403只有重定向不可用时才回退到 API。下载并解压 bundle从 Releases 拉取codegraph-target.tar.gz解压到versions/v目录。建立软链把启动器codegraph软链到~/.local/bin并用current软链标记当前版本。清理旧版本每次升级都会新装一个版本目录并重新指向current脚本会删掉其余旧 bundle避免无限堆积每个含运行时约 50 MB。POSIX 下即使某 daemon 还在运行旧 bundleinode 也会存活到进程退出删除目录不会影响运行中的进程。PATH 健康检查遍历$PATH既检查~/.local/bin是否真的在 PATH 上也检查是否有另一个更早的codegraph最常见是残留的npm i -g colbymchenry/codegraph会抢先执行——这正是文档提示装完打开新终端的原因。安装脚本支持三个环境变量见 install.sh 头部注释可用于精确控制安装位置与版本环境变量作用默认值CODEGRAPH_VERSION指定安装的 release tag默认 latest接受vX.Y.Z或裸X.Y.Z最新CODEGRAPH_INSTALL_DIRbundle 存放位置~/.codegraphCODEGRAPH_BIN_DIR启动器软链位置需加入 PATH~/.local/bin卸载同样是官方支持的操作curl -fsSL .../install.sh | sh -s -- --uninstall会移除~/.local/bin/codegraph与~/.codegraph。1.2 Windows 路径install.ps1 与 shell 版行为对齐架构探测得到win32-arm64/win32-x64从 Releases 下载codegraph-target.zip解压到%LOCALAPPDATA%\codegraph\current覆盖式升级并把current\bin追加进用户级 PATH需要重开终端生效。它还额外检查机器级 用户级两条 PATH若发现有更早的codegraph.cmd/.exe/.bat/.ps1会发出被遮蔽警告——对应 shell 版的同一类问题。1.3 已有 Node 环境npm 安装文档同时说明如果你本机已有 Nodenpm i -g colbymchenry/codegraph在任意受支持版本上都能工作且行为与 bundle 版一致无需编译、无原生构建。从 package.json 可确认关键事实包名为colbymchenry/codegraphbin字段把codegraph命令映射到dist/bin/codegraph.jsengines声明node: 20.0.0 25.0.0即 Node 20 至 24 受支持。CLI 入口 src/bin/codegraph.ts 会在此约束之外做硬拦截Node ≥ 25 因 V8 turboshaft 对 tree-sitter 大 WASM 语法的 Zone OOM 问题被直接拒绝Node 低于下限同样拒绝二者都可用CODEGRAPH_ALLOW_UNSAFE_NODE环境变量覆盖。无论哪种安装方式安装器都会把codegraph放进PATH但不会修改当前已打开的 shell——因此文档反复强调在下一步前打开一个新终端。这一点与脚本第 6 步的 PATH 检查逻辑一致新装的路径只有在新 shell 里才会被真正加载。2. 接入你的 Agentcodegraph installcodegraph install这一步把 CodeGraph 的 MCP 服务器写入你选定的各个 Agent 配置。文档明确这一步只连接 Agent、不索引任何代码。理解这条边界需要看安装器的设计意图——src/installer/index.ts 在结尾专门注明install wires up agents only — it deliberately does NOT index即刻意不索引以避免意外把$HOME之类的目录建了索引。真正建图是用户显式的codegraph init或index职责。2.1 支持的 Agent 目标文档列出了 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。源码中实际注册的目标更多——targets/registry.ts 的ALL_TARGETS还包含三个 GitHub Copilot 变体copilot-vscode、copilot-cli、copilot-jetbrains。也就是说codegraph install能配置的 Agent 集合是这 11 个目标顺序即多选提示里的显示顺序。安装器的工作流runInstallerWithOptions见 src/installer/index.ts大致是先问目标通过detectAll探测本机已装的 Agent把已识别的预勾选进多选框若什么都没探测到默认回退到 Claude保持历史最小惊讶行为。可选装 CLI 到 PATH交互式下会询问非交互--yes时跳过假定已存在。问位置global写~/.claude、~/.cursor等全项目生效或local写./.claude、./.cursor等仅当前项目。若所有所选目标都只支持 global如 Copilot CLI会跳过提示强制 global。可选自动允许权限仅对 Claude Code 有意义跳过其权限提示。逐个目标写入调用每个目标的install(location, {...})逐文件打印Created/Updated/Removed/Unchanged。收尾提示打印下一步codegraph init建图的提示并要求重启对应 Agent 生效。2.2codegraph install的可选参数CLI 入口 src/bin/codegraph.ts 为install定义了完整的参数集适合脚本化与 CI参数说明-t, --target ids目标 Agent逗号分隔 id或auto/all/none。缺省则交互式提示。-l, --location whereglobal或local。缺省则提示。-y, --yes非交互默认--locationglobal --targetauto自动允许打开。-i, --init接入 Agent 后顺带在当前目录执行codegraph init把接入 建图合并成一条命令配--yes可做无人值守引导。--no-permissions跳过写入自动允许权限列表仅 Claude Code。--print-config id打印指定 Agent 的 MCP 配置片段后退出不写任何文件。--refresh仅对已配置的 Agent 重写其表面说明块、MCP 条目、旧 hook 清理从不新增目标。codegraph upgrade会自动执行。--target的取值解析见 resolveTargetFlagauto返回所有detect().installed true的目标探测不到则回退[claude]all返回注册表全部none返回空列表调用方跳过 Agent 写入CSV 列表遇到未知 id 会抛出并打印全部已知 id。文档还给了一个便捷写法npx colbymchenry/codegraph会在一条命令里下载并运行安装器省去手动装 CLI 这一步仓库中 scripts/npm-shim.js 与 scripts/npm-sdk.js 即其配套 shim/SDK 入口。2.3 反向操作与升级codegraph uninstall是install的逆操作移除 MCP 服务器条目、说明块与权限但不删.codegraph/索引那是codegraph uninit的职责见 src/bin/codegraph.ts。升级走codegraph upgrade或重跑同一条安装命令它会重新运行安装脚本、换新版本目录并重指current软链随后通过--refresh让已配置 Agent 的表面与当前二进制的模板保持一致。3. 初始化每个项目codegraph initcd your-project codegraph initcodegraph init会创建本地.codegraph/目录并在同一步里构建完整图——一条命令即完成。文档强调只要存在.codegraph/目录你的 Agent 就会自动使用 CodeGraph 工具。 这正是存在性即启用的约定Agent 端依据该目录判断是否启用 CodeGraph 工具而不是靠全局开关。3.1codegraph init的可选参数CLI 入口 src/bin/codegraph.ts 为init提供了如下参数参数说明-i, --index已弃用索引现在默认执行仅为向后兼容保留。-f, --force即便路径看起来像主目录或文件系统根也允许初始化。-v, --verbose显示详细的 worker 生命周期与内存信息。-y, --yes非交互跳过所有提示取默认值适合脚本 / CI / 容器引导。安全护栏值得注意init/index都内置unsafeIndexRootReason检查当目标路径形如主目录或文件系统根时会拒绝执行--force作为显式覆盖从源头避免误把$HOME建了索引。此外当实时文件监听在本机被禁用例如 WSL2 的/mnt盘、或设置了CODEGRAPH_NO_WATCH时init之后会提示索引会冻结并询问是否改用 git 同步钩子commit / pull / checkout 后自动刷新对应 src/installer/index.ts 的offerWatchFallback。3.2 建图之后的生命周期理解init的后续行为有助于把一次建图变成持续同步codegraph index [path]全量重建索引等价于一次全新init。实现上它调用CodeGraph.recreate从底重建数据库而非打开旧图逐行删除——后者在大或已损坏的索引上会把主线程卡到触发存活看门狗见 src/bin/codegraph.ts。codegraph sync [path]对上次索引之后的增量变更做快速更新是日常保持新鲜度的首选。codegraph uninit [path]移除项目里的 CodeGraph删除.codegraph/并清理曾安装的 git 同步钩子删除前会请求确认-f跳过。至此三条命令的闭环成立curl/irm装 CLI →codegraph install接 Agent →cd 项目 codegraph init建图。Agent 端重启后即可在会话中自动调用 CodeGraph 工具无需每次手动触发。延伸阅读更完整的安装选项与环境细节Installation。建好图后如何验证与使用Your First Graph。CLI 全量命令参考reference/cli。想理解图是怎么构建与解析的可看 core-concepts/how-it-works。【免费下载链接】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），仅供参考 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本文以 CodeGraph 的 Quickstart 文档为主线完整还原安装 CLI → 接入 Agent → 初始化项目这条最短可用路径并结合仓库中 install.sh、install.ps1、CLI 入口 与 安装器编排逻辑 的源码解释每个步骤背后的实际行为、可复现的可选参数以及codegraph install为何只接 Agent、不索引代码、codegraph init为何一步建图。读完你可以独立完成从零到 Agent 自动调用 CodeGraph 工具的本地部署并能自行排查 PATH 冲突、目标 Agent 未识别、非交互式安装等常见问题。1. 安装 CLI一行命令无需 Node.jsQuickstart 的第一步是安装 CLI。CodeGraph 的官方分发方式是自包含 bundle——它把一份内嵌vendored的 Node 运行时和应用代码一起打包因此目标机器不需要预先安装 Node.js、构建工具或 npm适合在一台干净的 Linux VPS 上通过 SSH 直接部署。官方文档给出的两条一键命令如下# 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 | iex1.1 安装脚本到底做了什么逐行看 install.sh 可以确认这条命令完成的事情比下载一个二进制要多。它的执行顺序是平台探测通过uname -s/uname -m把系统映射成darwin/linux与arm64/x64组合成目标三元组如linux-arm64。不支持的平台或架构会直接报错退出。版本解析默认取 latest。脚本优先读取 GitHubreleases/latest的Web重定向而非调用 GitHub API来解析版本因为未认证的 API 有每小时 60 次的限流在共享主机 / CI 上很容易触发 403只有重定向不可用时才回退到 API。下载并解压 bundle从 Releases 拉取codegraph-target.tar.gz解压到versions/v目录。建立软链把启动器codegraph软链到~/.local/bin并用current软链标记当前版本。清理旧版本每次升级都会新装一个版本目录并重新指向current脚本会删掉其余旧 bundle避免无限堆积每个含运行时约 50 MB。POSIX 下即使某 daemon 还在运行旧 bundleinode 也会存活到进程退出删除目录不会影响运行中的进程。PATH 健康检查遍历$PATH既检查~/.local/bin是否真的在 PATH 上也检查是否有另一个更早的codegraph最常见是残留的npm i -g colbymchenry/codegraph会抢先执行——这正是文档提示装完打开新终端的原因。安装脚本支持三个环境变量见 install.sh 头部注释可用于精确控制安装位置与版本环境变量作用默认值CODEGRAPH_VERSION指定安装的 release tag默认 latest接受vX.Y.Z或裸X.Y.Z最新CODEGRAPH_INSTALL_DIRbundle 存放位置~/.codegraphCODEGRAPH_BIN_DIR启动器软链位置需加入 PATH~/.local/bin卸载同样是官方支持的操作curl -fsSL .../install.sh | sh -s -- --uninstall会移除~/.local/bin/codegraph与~/.codegraph。1.2 Windows 路径install.ps1 与 shell 版行为对齐架构探测得到win32-arm64/win32-x64从 Releases 下载codegraph-target.zip解压到%LOCALAPPDATA%\codegraph\current覆盖式升级并把current\bin追加进用户级 PATH需要重开终端生效。它还额外检查机器级 用户级两条 PATH若发现有更早的codegraph.cmd/.exe/.bat/.ps1会发出被遮蔽警告——对应 shell 版的同一类问题。1.3 已有 Node 环境npm 安装文档同时说明如果你本机已有 Nodenpm i -g colbymchenry/codegraph在任意受支持版本上都能工作且行为与 bundle 版一致无需编译、无原生构建。从 package.json 可确认关键事实包名为colbymchenry/codegraphbin字段把codegraph命令映射到dist/bin/codegraph.jsengines声明node: 20.0.0 25.0.0即 Node 20 至 24 受支持。CLI 入口 src/bin/codegraph.ts 会在此约束之外做硬拦截Node ≥ 25 因 V8 turboshaft 对 tree-sitter 大 WASM 语法的 Zone OOM 问题被直接拒绝Node 低于下限同样拒绝二者都可用CODEGRAPH_ALLOW_UNSAFE_NODE环境变量覆盖。无论哪种安装方式安装器都会把codegraph放进PATH但不会修改当前已打开的 shell——因此文档反复强调在下一步前打开一个新终端。这一点与脚本第 6 步的 PATH 检查逻辑一致新装的路径只有在新 shell 里才会被真正加载。2. 接入你的 Agentcodegraph installcodegraph install这一步把 CodeGraph 的 MCP 服务器写入你选定的各个 Agent 配置。文档明确这一步只连接 Agent、不索引任何代码。理解这条边界需要看安装器的设计意图——src/installer/index.ts 在结尾专门注明install wires up agents only — it deliberately does NOT index即刻意不索引以避免意外把$HOME之类的目录建了索引。真正建图是用户显式的codegraph init或index职责。2.1 支持的 Agent 目标文档列出了 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro。源码中实际注册的目标更多——targets/registry.ts 的ALL_TARGETS还包含三个 GitHub Copilot 变体copilot-vscode、copilot-cli、copilot-jetbrains。也就是说codegraph install能配置的 Agent 集合是这 11 个目标顺序即多选提示里的显示顺序。安装器的工作流runInstallerWithOptions见 src/installer/index.ts大致是先问目标通过detectAll探测本机已装的 Agent把已识别的预勾选进多选框若什么都没探测到默认回退到 Claude保持历史最小惊讶行为。可选装 CLI 到 PATH交互式下会询问非交互--yes时跳过假定已存在。问位置global写~/.claude、~/.cursor等全项目生效或local写./.claude、./.cursor等仅当前项目。若所有所选目标都只支持 global如 Copilot CLI会跳过提示强制 global。可选自动允许权限仅对 Claude Code 有意义跳过其权限提示。逐个目标写入调用每个目标的install(location, {...})逐文件打印Created/Updated/Removed/Unchanged。收尾提示打印下一步codegraph init建图的提示并要求重启对应 Agent 生效。2.2codegraph install的可选参数CLI 入口 src/bin/codegraph.ts 为install定义了完整的参数集适合脚本化与 CI参数说明-t, --target ids目标 Agent逗号分隔 id或auto/all/none。缺省则交互式提示。-l, --location whereglobal或local。缺省则提示。-y, --yes非交互默认--locationglobal --targetauto自动允许打开。-i, --init接入 Agent 后顺带在当前目录执行codegraph init把接入 建图合并成一条命令配--yes可做无人值守引导。--no-permissions跳过写入自动允许权限列表仅 Claude Code。--print-config id打印指定 Agent 的 MCP 配置片段后退出不写任何文件。--refresh仅对已配置的 Agent 重写其表面说明块、MCP 条目、旧 hook 清理从不新增目标。codegraph upgrade会自动执行。--target的取值解析见 resolveTargetFlagauto返回所有detect().installed true的目标探测不到则回退[claude]all返回注册表全部none返回空列表调用方跳过 Agent 写入CSV 列表遇到未知 id 会抛出并打印全部已知 id。文档还给了一个便捷写法npx colbymchenry/codegraph会在一条命令里下载并运行安装器省去手动装 CLI 这一步仓库中 scripts/npm-shim.js 与 scripts/npm-sdk.js 即其配套 shim/SDK 入口。2.3 反向操作与升级codegraph uninstall是install的逆操作移除 MCP 服务器条目、说明块与权限但不删.codegraph/索引那是codegraph uninit的职责见 src/bin/codegraph.ts。升级走codegraph upgrade或重跑同一条安装命令它会重新运行安装脚本、换新版本目录并重指current软链随后通过--refresh让已配置 Agent 的表面与当前二进制的模板保持一致。3. 初始化每个项目codegraph initcd your-project codegraph initcodegraph init会创建本地.codegraph/目录并在同一步里构建完整图——一条命令即完成。文档强调只要存在.codegraph/目录你的 Agent 就会自动使用 CodeGraph 工具。 这正是存在性即启用的约定Agent 端依据该目录判断是否启用 CodeGraph 工具而不是靠全局开关。3.1codegraph init的可选参数CLI 入口 src/bin/codegraph.ts 为init提供了如下参数参数说明-i, --index已弃用索引现在默认执行仅为向后兼容保留。-f, --force即便路径看起来像主目录或文件系统根也允许初始化。-v, --verbose显示详细的 worker 生命周期与内存信息。-y, --yes非交互跳过所有提示取默认值适合脚本 / CI / 容器引导。安全护栏值得注意init/index都内置unsafeIndexRootReason检查当目标路径形如主目录或文件系统根时会拒绝执行--force作为显式覆盖从源头避免误把$HOME建了索引。此外当实时文件监听在本机被禁用例如 WSL2 的/mnt盘、或设置了CODEGRAPH_NO_WATCH时init之后会提示索引会冻结并询问是否改用 git 同步钩子commit / pull / checkout 后自动刷新对应 src/installer/index.ts 的offerWatchFallback。3.2 建图之后的生命周期理解init的后续行为有助于把一次建图变成持续同步codegraph index [path]全量重建索引等价于一次全新init。实现上它调用CodeGraph.recreate从底重建数据库而非打开旧图逐行删除——后者在大或已损坏的索引上会把主线程卡到触发存活看门狗见 src/bin/codegraph.ts。codegraph sync [path]对上次索引之后的增量变更做快速更新是日常保持新鲜度的首选。codegraph uninit [path]移除项目里的 CodeGraph删除.codegraph/并清理曾安装的 git 同步钩子删除前会请求确认-f跳过。至此三条命令的闭环成立curl/irm装 CLI →codegraph install接 Agent →cd 项目 codegraph init建图。Agent 端重启后即可在会话中自动调用 CodeGraph 工具无需每次手动触发。延伸阅读更完整的安装选项与环境细节Installation。建好图后如何验证与使用Your First Graph。CLI 全量命令参考reference/cli。想理解图是怎么构建与解析的可看 core-concepts/how-it-works。【免费下载链接】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），仅供参考