用 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 的目的不是让并行更多，而是让并行可控。