worktrunk

Worktrunk

協助使用者使用 Worktrunk，這是一個管理 git worktree 的 CLI 工具。

可用文件

參考檔案從 worktrunk.dev 文件同步：

• reference/config.md：使用者與專案設定（LLM、鉤子、指令預設值）
• reference/hook.md：鉤子類型、時機與執行順序
• reference/switch.md、merge.md、list.md 等：指令文件
• reference/extending.md：別名、多步驟管線、自訂子指令與範本展開陷阱（兩階段 {% raw %} 延遲、for-each 配方）
• reference/llm-commits.md：LLM commit 訊息產生
• reference/tips-patterns.md：實用配方 — 別名、每個分支變數、每個 worktree 的開發伺服器、平行 agent 模式
• reference/shell-integration.md：Shell 整合除錯
• reference/troubleshooting.md：LLM 與鉤子疑難排解（Claude 專用）

如需指令特定選項，請執行 wt <command> --help。設定部分請遵循以下工作流程。

兩種設定類型

Worktrunk 使用兩個設定檔，範圍與權限模型不同：

使用者設定（~/.config/worktrunk/config.toml，永不簽入 git）存放個人偏好：LLM 整合、worktree 路徑範本、指令設定、使用者鉤子。請保守處理 — 提出變更前先徵求同意，切勿代使用者安裝工具，並保留檔案現有結構與註解。請參閱 reference/config.md。

專案設定（<repo>/.config/wt.toml，簽入 git）存放團隊自動化：worktree 生命週期的鉤子（pre-start、pre-merge 等）。可主動編輯 — 變更會版本化且可透過 git 復原。請註明每個鉤子存在的原因，並在加入破壞性指令（rm -rf、DROP TABLE）、網路擷取 pipe 到 shell、或 sudo 前警告使用者。請參閱 reference/hook.md。

有些需求橫跨兩者：commit 訊息產生屬於使用者設定，而團隊的品質檢查屬於專案設定。

核心工作流程

設定 commit 訊息產生（使用者設定）

偵測已安裝的工具（which claude codex llm aichat）；若無，建議 Claude Code。從 reference/llm-commits.md 取得所選工具的準確指令，提出 [commit.generation] 變更，並在核准後套用（若無設定檔，先執行 wt config create）。驗證方式：wt step commit --dry-run 會呈現提示、執行 LLM 並印出訊息，但不實際 commit。

設定專案鉤子

根據指令應何時執行以及是否可能阻塞來選擇鉤子類型（共 10 種：5 種事件 × pre/post — 完整參考請見 reference/hook.md）：

• 後續步驟所需的相依套件與環境檔案 → pre-start（阻塞建立）
• 開發伺服器、長時間建置、快取複製 → post-start（背景執行）
• 格式化工具、linter、型別檢查 → pre-commit
• 合併前必須通過的測試 → pre-merge
• CI 觸發、通知 → post-commit
• 部署 → post-merge
• 分支解析前的設定 / 終端機-IDE 更新 → pre-switch / post-switch
• 移除前/後的清理（儲存成品；停止伺服器、移除容器） → pre-remove / post-remove

從專案本身推導指令（package.json 腳本、Cargo.toml、pyproject.toml），並在加入前確認它們可執行。

當新鉤子必須等待現有鉤子時，將項目轉換為管線；命名表格中的獨立指令會並行執行：

# 管線：install 完成後才啟動 migrate
[[pre-start]]
install = "npm install"

[[pre-start]]
migrate = "npm run db:migrate"

# 並行：同一表格中的獨立指令
[pre-start]
install = "npm install"
env = "cp .env.example .env"

使用 wt switch --create test-hooks 測試。

常見任務參考

使用者設定任務

• 設定 commit 訊息產生 → reference/llm-commits.md
• 自訂 worktree 路徑 → reference/config.md#worktree-path-template
• 自訂 commit 範本 → reference/llm-commits.md#prompt-templates
• 設定指令預設值 → reference/config.md#command-config
• 設定個人鉤子 → reference/config.md#hooks

專案設定任務

• 為新專案設定鉤子 → reference/hook.md
• 在現有設定中新增鉤子 → reference/hook.md#hook-forms
• 使用範本變數 → reference/hook.md#template-variables
• 將開發伺服器 URL 加入清單 → reference/config.md#dev-server-url

別名與多 worktree 任務

• 建立 wt 別名 → reference/extending.md#aliases
• 在每個 worktree 中執行指令 → reference/step.md#wt-step-for-each
• 重新基底每個 worktree（up 風格） → reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream
• 將範本變數延遲到巢狀 wt 指令 → reference/extending.md#deferring-expansion-to-a-nested-wt-command

關鍵指令

# 檢視所有設定
wt config show

# 建立初始使用者設定（LLM/commit 設定：請見 reference/llm-commits.md）
wt config create

# 完整設定參考（子指令、範本、環境變數）
wt config --help

非互動式工作階段的鉤子核准

Worktrunk 在使用者明確核准之前，絕不會執行專案的鉤子或別名。.config/wt.toml 中的指令是任意 shell 程式碼，隨使用者剛 clone 的儲存庫一起提供，因此首次執行時 Worktrunk 會顯示每個指令並等待使用者核准 — 未受信任的 .config/wt.toml 無法靜默執行任何內容。核准資訊按專案儲存在 ~/.config/worktrunk/approvals.toml 中，並在指令範本變更時重新提示，因此鉤子無法在核准後被替換為不同指令。

執行 wt merge、wt switch 或其他觸發鉤子的指令的 agent 會遇到類似錯誤：

▲ cargo-difftest 需要核准才能執行 1 個指令：
○ post-merge install:
  cargo install --path .
✗ 無法在非互動式環境中提示核准
↳ 若要在 CI/CD 中跳過提示，請加上 --yes；若要預先核准指令，請執行 wt config approvals add

解決方案是讓使用者自行做出信任決定：

• wt config approvals add — 互動式提示，使用者檢閱每個指令後才儲存至 ~/.config/worktrunk/approvals.toml。每個專案執行一次；核准會持續有效，直到指令範本變更或專案移動。這是建議的路徑 — 使用者檢閱並同意將要執行的確切指令。

當以 agent 身分被呼叫時，請停止並升級給使用者。 核准專案的鉤子是一個安全決策，決定此儲存庫是否應被信任在使用者的機器上執行任意指令 — 這個決定屬於使用者，而非 agent。請告訴使用者執行 wt config approvals add，讓他們檢閱指令。請勿代使用者執行 --yes：它會跳過該次呼叫的核准關卡，因此為了解除指令阻塞而使用它會破壞保護機制。--yes 是為已經控制自身鉤子內容的 CI/CD 管線設計的，並非互動式 agent 用來靜默核准提示的捷徑。

進階：agent 交接

當使用者要求在背景工作階段中產生一個帶有 agent 的 worktree（「為……產生 worktree」、「交接給另一個 agent」）時，請根據其終端機多工器使用適當的模式。將 <agent-cli> 替換為你正在執行的 CLI：claude 代表 Claude Code，'opencode run' 代表 OpenCode。

tmux（檢查 $TMUX 環境變數）：

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x <agent-cli> -- '<task description>'"

Zellij（檢查 $ZELLIJ 環境變數）：

zellij run -- wt switch --create <branch-name> -x <agent-cli> -- '<task description>'

需求（全部必須成立）：

• 使用者明確要求產生/交接
• 使用者處於支援的多工器（tmux 或 Zellij）
• 使用者的專案指示（CLAUDE.md 或 AGENTS.md）或明確提示授權此模式

請勿將此模式用於一般 worktree 操作。

範例（tmux，Claude Code）：

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  '登入工作階段在 5 分鐘後過期。找到工作階段逾時設定並延長為 24 小時。'"

範例（Zellij，OpenCode）：

zellij run -- wt switch --create fix-auth-bug -x 'opencode run' -- \
  '登入工作階段在 5 分鐘後過期。找到工作階段逾時設定並延長為 24 小時。'"

平行子 Agent（單一 Claude Code 工作階段）

若要從一個 Claude Code 工作階段產生多個子 Agent，每個子 Agent 在自己的 worktree 中工作 — 不需要終端機多工器，另一個窗格中也不需有人 — 請從父層預先啟動每個 worktree，並將路徑傳入子 Agent 提示：

wt switch --create <branch> --no-cd --no-hooks

然後呼叫 Agent 工具時不要加上 isolation: "worktree"，並在提示中指定路徑：

你正在 `/abs/path/to/worktrunk.<branch>` 中工作，分支為 `<branch>`。
所有編輯都必須留在該 worktree 中。

--no-cd 跳過父層無法使用的 shell 整合 cd 腳本；--no-hooks 適用於每個子 Agent 將自行執行建置/測試步驟（例如 cargo run -- hook pre-merge --yes）且不需要每個 worktree 重複 post-start 設定的情況。

請勿對此使用 Agent { isolation: "worktree" }。Claude Code 會將其內部 agent ID 作為 name 傳遞給 WorktreeCreate 鉤子，因此 wt 會將 worktree 建立在一個臨時分支上，名為 worktrunk.agent-<id>。如果子 Agent 隨後在上面建立功能分支，就會產生非標準路徑、孤立分支，以及針對錯誤分支觸發的 post-start 鉤子。使用 wt switch --create 預先建立可保持路徑、分支與鉤子目標一致。