開始使用

這頁假設你已經裝好其中一個支援的工具（Claude Code、VS Code Copilot、OpenAI Codex CLI、OpenCode、Cursor、Windsurf、Aider 或 Cline），想把 Coograph 加進專案。

需求

• Python 3.10+
• uv（建議；首次執行會自動安裝相依套件）
• 一個 Git 儲存庫

安裝

在專案根目錄：

# Clone Coograph as a sibling directory
git clone https://github.com/paullukic/coograph.git ../coograph

接著在 AI 工具的聊天視窗觸發初始化器。每個工具有自己的呼叫語法。

自然語言改寫（「initialize the project」、「set up coograph」）在每個工具都能用 — 每份設定檔都把這些觸發語和斜線形式並列。

初始化器會自動偵測技術堆疊、填入 .github/copilot-instructions.md 的 _TBD_ 佔位符，並（若你同意）為專案建立程式碼圖。

Codex CLI 說明

Codex CLI 註冊自訂工作流程的方式跟另外七個工具不同。用 Codex 的話，先掃一眼這節。

斜線是保留字

Codex 把 / 留給約 30 個內建指令。輸入 /coograph-init 會回 Unrecognized command。改用：

• $coograph-init — 顯式 $skill-name 呼叫。
• /skills — 內建指令，列出所有已安裝的 skill。用來確認 Coograph 已載入。
• 自然語言 — 「initialize the project」、「set up coograph」、「wire up coograph in this repo」。Codex 會比對 skill 描述並自動啟用。

Codex 在哪裡找 skill

Codex 依以下優先順序掃描這些目錄（出處）：

1. $CWD/.agents/skills
2. 父目錄的 .agents/skills
3. $REPO_ROOT/.agents/skills
4. $HOME/.agents/skills
5. /etc/codex/skills
6. 內建系統 skill

Coograph 把 .agents/skills/coograph-init/SKILL.md 放在儲存庫根目錄，所以專案裡任何位置都能在第 3 步找到。

驗證 skill 是否載入

在 Codex 工作階段執行 /skills。如果沒看到 coograph-init，要嘛你的 Codex 版本太舊不支援 skill，要嘛專案的 .agents/skills/ 目錄不見了 — 從另一個支援的工具執行 /coograph-init 還原。

手動建立圖

如果跳過了初始化器的程式碼圖步驟，之後也可以建：

uv run --with-requirements .github/code-graph/requirements.txt \
  .github/code-graph/server.py --build

它會解析儲存庫裡的每個原始檔，並寫入 .code-graph/graph.db（SQLite、MB 等級、列入 gitignore）。

接上 MCP 伺服器

Coograph 透過 Model Context Protocol 把圖查詢開放給 AI 工具。

Claude Code（儲存庫根目錄的 .mcp.json）

{
  "mcpServers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ]
    }
  }
}

VS Code Copilot（.vscode/mcp.json）

{
  "servers": {
    "code-graph": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with-requirements",
        "${workspaceFolder}/.github/code-graph/requirements.txt",
        "${workspaceFolder}/.github/code-graph/server.py"
      ]
    }
  }
}

第一個查詢

在你選用代理的對話裡：

「要替 OrderService.place_order 加快取，我得讀哪些檔案？」

代理會對圖呼叫 get_minimal_context(...)，回傳四到六個檔案，而不是 grep 每筆比對。

自動更新

裝一次 git 鉤子：

cp .github/code-graph/post-commit  .git/hooks/post-commit
cp .github/code-graph/post-merge   .git/hooks/post-merge
cp .github/code-graph/post-rewrite .git/hooks/post-rewrite
chmod +x .git/hooks/post-{commit,merge,rewrite}

每次 commit、merge 或 rebase 時，圖只重新解析 SHA-1 有變動的檔案。更新只要毫秒。

下一步

• 程式碼圖 — graph.db 裡有什麼，怎麼查
• 工作流程 — Plan → Propose → Apply，安全地做大改動

在 GitHub 編輯本頁 →