AI Learn
OpenAI Codex · Practical Tutorial

Use Codex Worktrees to isolate parallel coding tasks

Run independent Codex chats in separate Git worktrees so experiments, fixes and long-running tasks do not collide with your active checkout.

Reviewed September 20, 2026Independent tutorialFeatures may vary
Not official support. AI Learn is an independent education site. Check the provider’s current documentation for plan-specific limits, pricing and feature availability.
Before you start

Worktrees are isolation, not magic merge conflict prevention. Start each task from the right branch, give tasks non-overlapping ownership where possible, and review the handoff before bringing changes back into your local checkout.

1. Confirm the project is a Git repository and choose the correct base branch

Confirm the repository is clean enough to branch and identify the exact base commit or branch. Starting parallel work from different unseen states makes later comparison and integration unreliable.

2. Start a Codex chat in a worktree for one self-contained task

Create one worktree per self-contained task and give it a descriptive branch name. Each worktree should have a clear owner, scope and expected test command before Codex begins editing.

3. Keep the task scoped so another parallel worktree does not own the same files

Partition file ownership where possible. If two tasks must touch the same core file, treat them as integration-dependent rather than pretending they are fully parallel.

4. Run tests inside the worktree and review its diff before handoff

Run the relevant tests inside each worktree and inspect its diff independently. A passing sibling worktree says nothing about this branch because dependencies and edits are isolated.

5. Move or merge the work back deliberately, then clean up stale managed worktrees

Integrate deliberately with merge/rebase/cherry-pick according to the repository policy, rerun combined tests, then remove stale worktrees only after the integrated result is safe.

Try this prompt

Create this task in a separate worktree from [base branch]. Scope ownership: [files/module]. Do not edit [overlap area]. Run [tests] inside the worktree. Before handoff, summarize commits, uncommitted changes, conflicts you expect and the safest integration path.

Common mistakes

Starting from the wrong branch; two worktrees changing the same shared file set; assuming detached HEAD behavior is a normal feature branch; handing off without tests; leaving permanent worktrees and stale dependencies indefinitely.

Finish check

Each parallel task has an isolated checkout, tests run in its own environment, the diff is understandable, and integration back to the main checkout is deliberate rather than accidental.

开始之前

Worktree 提供的是隔离,不代表以后绝对不会有合并冲突。每个任务都要从正确分支开始,尽量分配不重叠的修改范围,并在把结果带回本地前认真检查 Handoff。

1. 确认项目是 Git 仓库,并选择正确基准分支

先确认仓库状态适合分支,并明确所有并行任务从哪个 Base Commit/Branch 开始。不同任务如果从不一致的隐藏状态出发,最后的比较和整合就不可信。

2. 为一个独立任务在 Worktree 中启动 Codex 会话

每个自包含任务建立一个 Worktree,并使用能看懂的 Branch 名。Codex 开始修改前,每个 Worktree 都应该有清楚的负责人、范围和预期测试命令。

3. 限制任务范围,避免另一个并行 Worktree 负责同一批文件

尽量让不同任务拥有不同文件。如果两个任务必须同时修改同一个核心文件,就应承认它们存在整合依赖,而不是假装可以完全并行。

4. 在 Worktree 内运行测试并审查 diff,再执行 Handoff

在每个 Worktree 内单独跑对应测试并检查自己的 Diff。其他 Worktree 测试通过不能证明当前分支安全,因为依赖状态和修改内容是隔离的。

5. 有意识地把工作移回/合并到本地,并清理过期的托管 Worktree

按照仓库策略明确选择 Merge/Rebase/Cherry-pick,整合后再跑一次组合测试。确认主结果安全以后,才清理不再需要的 Worktree。

可以直接套用的提示词

从 [base branch] 为这个任务建立独立 Worktree。负责范围:[文件/模块]。不要修改 [重叠区域]。在 Worktree 内运行 [tests]。Handoff 前总结提交、未提交改动、预期冲突和最安全的集成方式。

常见错误

从错误分支开始;两个 Worktree 同时改同一批共享文件;把 detached HEAD 当成普通长期功能分支;没测试就 Handoff;永久 Worktree 和旧依赖长期不清理。

完成检查

每个并行任务都有独立工作目录,测试在自己的环境中运行,diff 清晰可理解,带回主工作区的过程是有计划的,而不是碰巧发生。

開始之前

Worktree 提供的是隔離,不代表以後絕對不會有合併衝突。每個任務都要從正確分支開始,盡量分配不重疊的修改範圍,並在把結果帶回本地前認真檢查 Handoff。

1. 確認專案是 Git 儲存庫,並選擇正確基準分支

先確認倉庫狀態適合分支,並明確所有並行任務從哪個 Base Commit/Branch 開始。不同任務如果從不一致的隱藏狀態出發,最後的比較和整合就不可信。

2. 為一個獨立任務在 Worktree 中啓動 Codex 會話

每個自包含任務建立一個 Worktree,並使用能看懂的 Branch 名。Codex 開始修改前,每個 Worktree 都應該有清楚的負責人、範圍和預期測試命令。

3. 限制任務範圍,避免另一個並行 Worktree 負責同一批檔案

盡量讓不同任務擁有不同檔案。如果兩個任務必須同時修改同一個核心檔案,就應承認它們存在整合依賴,而不是假裝可以完全並行。

4. 在 Worktree 內執行測試並審查 diff,再執行 Handoff

在每個 Worktree 內單獨跑對應測試並檢查自己的 Diff。其他 Worktree 測試通過不能證明當前分支安全,因為依賴狀態和修改內容是隔離的。

5. 有意識地把工作移回/合併到本地,並清理過期的托管 Worktree

按照倉庫策略明確選擇 Merge/Rebase/Cherry-pick,整合後再跑一次組合測試。確認主結果安全以後,才清理不再需要的 Worktree。

可以直接套用的提示詞

從 [base branch] 為這個任務建立獨立 Worktree。負責範圍:[檔案/模塊]。不要修改 [重疊區域]。在 Worktree 內執行 [tests]。Handoff 前總結提交、未提交改動、預期衝突和最安全的集成方式。

常見錯誤

從錯誤分支開始;兩個 Worktree 同時改同一批共享檔案;把 detached HEAD 當成普通長期功能分支;沒測試就 Handoff;永久 Worktree 和舊依賴長期不清理。

完成檢查

每個並行任務都有獨立工作目錄,測試在自己的環境中執行,diff 清晰可理解,帶回主工作區的過程是有計劃的,而不是碰巧發生。

Official references

Check current product details at the source

Related practical tutorials

Continue with another single-task workflow.

All tutorials →