安裝指南 · codegraph 繁中教學站

1. 安裝 CLI

免 Node.js——一條指令抓對應 OS 的 build（內建 bundle runtime，不用編譯）：

# 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

已有 Node？用 npm 也可以（任何版本都行）

npm i -g @colbymchenry/codegraph

CodeGraph 自帶 runtime，無原生 build。裝完 codegraph 會在 PATH 上，但不會改你目前的 shell——下一步之前先開一個新終端。

注意：安裝器只把 codegraph 放到 PATH，不會自動接上你的 agent、也不會索引任何程式。那是下一步 codegraph install 與下下步 codegraph init 的事。

2. 接上你的 agent（codegraph install）

在新終端執行，自動偵測並設定以下 9 個 agent，把 CodeGraph MCP server 接進每個平台：

codegraph install

Claude Code · Cursor · Codex CLI · opencode · Hermes Agent
Gemini CLI · Antigravity IDE · Kiro
GitHub Copilot：VS Code 的 Copilot Chat（copilot-vscode）、Copilot CLI（copilot-cli）、JetBrains 外掛（copilot-jetbrains）

它也會在 agent 的 instructions 檔（CLAUDE.md / AGENTS.md / GEMINI.md）寫入 marker-fenced 段落，告訴 sub-agent 用 codegraph explore 指令。非互動（CI/腳本）：

codegraph install --yes                                  # 自動偵測，全站安裝
codegraph install --target=cursor,claude --yes           # 指定平台
codegraph install --target=auto --location=local         # 偵測平台，專案本機
codegraph install --print-config codex                   # 只印設定片段，不寫檔

3. 每個專案建圖（codegraph init）

cd your-project
codegraph init

一次做兩件事：建立 .codegraph/ 目錄 + 建好全量圖譜。之後 agent 在有 .codegraph/ 的目錄下就會自動用 CodeGraph 工具。

本站實測：對 codegraph 自己跑 codegraph init（v1.5.0）

$ codegraph init
┌  Initializing CodeGraph
◆  Initialized in <repo-root>
Scanning files...
Parsing code...
Resolving refs...
Linking dynamic dispatch...
◆  Indexed 570 files
●  12,733 nodes, 44,903 edges in 1.7s
└  Done

重設 / 移除

codegraph uninstall          # 從所有 agent 移除設定，也移除 CLI（--keep-cli 只移除設定）
codegraph uninit [path]      # 移除單一專案的 .codegraph/ 索引
codegraph upgrade            # 升級到最新版（--check 看有沒有新版）
codegraph status             # 檢查索引健康度與統計

codegraph uninstall 會先列出它找到的每一份安裝（standalone bundle / npm global / launcher link）再刪。

疑難排解速查

症狀	解法
`CodeGraph not initialized`	先在你專案目錄跑 `codegraph init`。
索引很慢	確認 `node_modules` 等大目錄被排除（預設已排除）；可用 `--quiet` 減少輸出。
MCP `database is locked`	新版已用 node:sqlite WAL 模式，並行讀取不會被寫入阻塞。老版本請重裝；`codegraph status` 顯示非 `wal` journal 時把專案移到本機磁碟。
MCP server 連不上	agent 會自己啟動 server。確認 `codegraph status` 健康、路徑正確，或重跑 `codegraph install` 重寫設定。
缺少符號	MCP server 會自動同步（等個幾秒）；確認檔案語言受支援且不在 gitignore / 預設排除目錄。

看完這頁你應該能說出：三步（裝 CLI → codegraph install → codegraph init）各自的職責、9 個 agent 平台、為什麼裝完要開新終端、uninstall 與 uninit 的差別。