用 Worktrees 並行開發

Worktree 讓 Codex 可以在同一個 Git repository 中為不同任務建立隔離 checkout。它適合並行任務、後臺任務和實驗性改動，核心價值是減少對當前 Local checkout 的干擾。

當你或其他 agent 正在修改當前工作樹時，優先考慮 worktree 或更窄檔案邊界。不要讓多個任務直接擠在同一個 checkout 裡。

Worktrees

檢視 Codex App worktree 的官方說明。

App core

理解 App 中 threads、modes、Git、terminal 和 review 的關係。

Automations

瞭解 automations 如何使用後臺 worktrees。

為什麼需要 worktree

flowchart LR
    Local["Local checkout<br/>你的當前工作"] --> Risk["直接並行修改會衝突"]
    WorktreeA["Worktree A<br/>任務 1"] --> Review["獨立審查"]
    WorktreeB["Worktree B<br/>任務 2"] --> Review
    Risk --> WorktreeA
    Risk --> WorktreeB

適合：

同一 repo 中並行跑多個 Codex thread。
讓後臺任務不影響當前 IDE 和 dev server。
試一個方案但不想汙染本地工作樹。
等 Codex 完成後再決定是否 handoff 回 Local。

不適合：

非 Git 專案。
只改一個小檔案的簡單任務。
你不熟悉 Git worktree 和 branch 限制。

Local、Worktree、Handoff

Local：

你當前日常使用的 checkout。
適合前臺開發、IDE、已有 dev server。

Worktree：

同一 repo 的另一份 checkout。
有自己的檔案副本。
與 repo 共享 Git metadata。
適合隔離任務。

Handoff：

在 Local 和 Worktree 之間移動 thread 和程式碼。
適合把後臺任務帶回前臺審查或繼續開發。

不要手動在多個 worktree 中同時 checkout 同一個 branch。Git 會阻止這種情況，以避免同一個 branch 被多個 working tree 同時修改。

基本流程

在 App 中建立新 thread。
選擇 Worktree mode。
選擇起始 branch。
提交任務 prompt。
Codex 在隔離 worktree 中工作。
在 App 中審查 diff。
選擇繼續在 worktree 上建立 branch，或 handoff 回 Local。

任務 prompt 仍要寫清：

目標。
檔案範圍。
禁止事項。
驗證命令。
是否允許新增依賴。

Worktree 只隔離檔案，不替你定義任務邊界。

官方流程裡，Worktree mode 會讓 Codex 基於你選擇的 starting branch 建立 Git worktree。預設情況下，Codex 使用 detached HEAD，這樣可以建立多個 worktree 而不汙染本地 branches。需要長期保留時，再在 worktree 上建立 branch。

什麼時候留在 worktree

留在 worktree 適合：

任務可以獨立驗證。
依賴和環境在 worktree 中可用。
準備直接從 worktree 建立 branch 和 PR。
不需要你當前 Local 的特殊狀態。

檢查：

測試能否在 worktree 中執行。
dev server 是否能獨立啟動。
是否有未提交依賴或環境檔案缺失。

什麼時候 handoff 回 Local

Handoff 回 Local 適合：

你想用常用 IDE 審查。
只能執行一個本地服務例項。
任務需要你當前 Local 的未提交上下文。
要繼續人工開發。

Handoff 前先確認：

Local 工作樹是否乾淨或已儲存。
是否會覆蓋當前未提交改動。
.gitignore 檔案是否需要額外處理。
目標 branch 是否已被其他 worktree checkout。

Handoff 會移動 thread 和程式碼。Codex 會處理必要的 Git 操作，因為 Git 不允許同一個 branch 同時 checkout 在多個 worktree 中。

如果你在 worktree 上建立了 feature/a branch，再試圖在 Local checkout 同一個 branch，Git 會報錯：

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

這種情況下，不要強行改 Git metadata。要麼把 worktree 切到別的 branch，要麼用 Handoff 把 thread 和改動帶回 Local。

Codex-managed 和 permanent worktrees

Codex-managed worktree：

預設由 Codex 為單個 thread 建立。
更輕量，適合一次性任務。
thread handoff 回 worktree 時會回到同一個關聯 worktree。
會受自動清理策略影響。

Permanent worktree：

從 project sidebar 的 three-dot menu 建立。
會成為長期 project。
不會因為普通 thread archive 自動刪除。
適合長期分支、長期環境或固定實驗線。

不要把 permanent worktree 當作隨手建立的草稿目錄。它會佔用磁碟和認知負擔。

自動清理和磁碟空間

Worktree 會佔磁碟空間，尤其當專案有依賴、build cache 或大型生成物時。

建議：

定期清理不再需要的 Codex-managed worktrees。
Permanent worktree 只用於長期環境。
不把 worktree 當備份。
重要改動及時建立 branch 或 PR。

自動清理前，仍要確認是否有未儲存的重要工作。

官方文件說明：Codex 預設保留最近 15 個 Codex-managed worktrees。你可以在 settings 裡調整上限或關閉自動刪除。

Codex-managed worktree 不會自動刪除的情況包括：

conversation 被 pinned。
thread 仍在進行。
worktree 是 permanent worktree。

會自動刪除的情況包括：

associated thread 被 archive。
需要刪除舊 worktrees 以保持數量限制。

刪除前 Codex 會儲存 snapshot。如果你重新開啟對應 conversation，可以看到恢復選項。

local environment 配合

worktree 是另一份 checkout，只包含 Git 跟蹤檔案。依賴、生成檔案、未提交配置、本地快取通常不會自動出現。

因此，worktree 任務應配合 local environment：

在 .codex 中配置 setup script。
建立 worktree 時自動安裝依賴或初始化。
用 actions 啟動 dev server、build、test。
讓 Codex 在 worktree terminal 中驗證。

如果沒有 setup script，很多“worktree 跑不起來”的問題其實不是程式碼問題，而是環境沒有初始化。

並行邊界

Worktree 適合並行，但仍要定義邊界：

場景	建議
兩個任務改不同模組	可以分別開 worktree
兩個任務都改同一個核心檔案	不建議並行
一個任務只讀分析，一個任務寫程式碼	只讀任務不一定需要 worktree
後臺 automation	Git repo 中預設適合 dedicated worktree
當前 Local 有未提交關鍵改動	先儲存或明確是否帶入 starting branch

安全檢查清單

使用 worktree 前確認：

專案是 Git repository。
當前 Local dirty files 已知。
任務範圍不會和其他 agent 衝突。
驗證命令能在 worktree 中執行。
不依賴 Local 中未提交但未帶入的檔案。
Handoff 前已看過 diff。

Worktree 的目的不是讓並行更多，而是讓並行可控。