用 Worktrees 并行开发

在 Codex App 中，worktrees 让 Codex 可以在同一个 project 里并行运行多个 independent tasks，彼此不干扰。

对于 Git repositories，automations 会在 dedicated background worktrees 上运行，避免和你正在进行的工作冲突。

在 non-version-controlled projects 中，automations 会直接在 project directory 中运行。

你也可以手动在 worktree 上启动 threads，并用 Handoff 在 Local 和 Worktree 之间移动 thread。

What's a worktree

Worktrees 只适用于属于 Git repository 的 projects，因为底层使用的是 Git worktrees。

一个 worktree 可以理解成 repository 的第二份 checkout。每个 worktree 都有 repo 中每个文件的一份 copy，但它们共享 commits、branches 等 metadata，也就是 .git folder。这样你可以并行 checkout 并处理多个 branches。

Terminology

术语	含义
Local checkout	你自己创建的 repository。在 Codex App 中有时简称 Local。
Worktree	Codex App 从 local checkout 创建的 Git worktree。
Handoff	在 Local 和 Worktree 之间移动 thread 的流程。Codex 会处理必要 Git operations，尽量安全地移动你的 work。

Why use a worktree

使用 worktree 的主要原因：

让 Codex 并行工作，同时不打扰你当前的 Local setup。
把 background work 排队运行，你继续专注 foreground。
等你准备 inspect、test 或更直接协作时，再把 thread 移入 Local。

开始使用

Worktrees 需要 Git repository。先确认你选择的 project 位于 Git repository 中。

基本流程：

Select "Worktree"

在 new thread view 中，在 composer 下方选择 Worktree。

可选：选择一个 local environment，为 worktree 运行 setup scripts。
Select the starting branch

在 composer 下方选择 Git branch，作为 worktree 的基础。它可以是 main / master branch、feature branch，或当前带有 unstaged local changes 的 branch。
Submit your prompt

提交 task 后，Codex 会基于你选择的 branch 创建 Git worktree。默认情况下，Codex 会在 "detached HEAD" 中工作。
Choose where to keep working

准备好后，你可以继续直接在 worktree 上工作，也可以把 thread hand off 到 local checkout。Hand off 到 local，或从 local hand off 出去，都会同时移动 thread 和 code，让你在另一个 checkout 中继续。

Working between Local and Worktree

Worktrees 的观感和 local checkout 很像，差别在于它们在 workflow 中的位置。你可以把 Local 理解成 foreground，把 Worktree 理解成 background。Handoff 让你在两者之间移动 thread。

Handoff 底层会处理在两个 checkouts 之间安全移动 work 所需的 Git operations。这很重要，因为 Git 只允许一个 branch 同时 checkout 在一个地方。如果你在 worktree 中 checkout 了某个 branch，就不能同时在 local checkout 中 checkout 同一个 branch，反过来也一样。

常见路径有两种：

只在 worktree 上工作。当你可以直接在 worktree 上验证 changes 时，这条路径最合适。例如，你已经通过 local environment setup script 安装好 dependencies 和 tools。
把 thread hand off 到 Local。当你想把 thread 带回 foreground 时使用。例如，你想在常用 IDE 中 inspect changes，或只能运行一个 app instance。

Option 1: Working on the worktree

如果你想一直在 worktree 中处理 changes，在 thread header 中点击 Create branch here，把这个 worktree 转成 branch。

之后你可以：

commit changes
push branch 到 remote repository
在 GitHub 上打开 pull request

你可以用 header 中的 Open button 把 IDE 打开到 worktree，也可以使用 integrated terminal，或在 worktree directory 中执行其他需要的操作。

官方截图：

记住：如果你在 worktree 上创建 branch，就不能在任何其他 worktree 中 checkout 同一 branch，包括 local checkout。

Option 2: Handing a thread off to Local

如果你想把 thread 带到 foreground，点击 thread header 中的 Hand off，并移动到 Local。

当你想在常用 IDE window 中阅读 changes、运行现有 development server，或在日常使用的同一环境中验证工作时，这条路径很好用。

Codex 会处理在 worktree 和 local checkout 之间安全移动 thread 所需的 Git steps。

每个 thread 会长期保留同一个 associated worktree。如果你之后再把 thread hand back 到 worktree，Codex 会把它送回同一个 background environment，让你从之前的位置继续。

官方截图：

你也可以反向操作：如果你已经在 Local 中工作，但想释放 foreground，可以用 Hand off 把 thread 移到 worktree。这样 Codex 可以继续在 background 工作，你把注意力切回本地其他事情。

由于 Handoff 使用 Git operations，.gitignore 中的 files 不会随 thread 一起移动。

Advanced details

Codex-managed and permanent worktrees

默认情况下，threads 使用 Codex-managed worktree。这类 worktrees 设计成轻量、可丢弃。一个 Codex-managed worktree 通常专属于一个 thread；如果你之后把 thread hand back 回 worktree，Codex 会回到同一个 worktree。

如果你想要 long-lived environment，可以在 sidebar 中 project 的 three-dot menu 创建 permanent worktree。它会作为独立 project 创建新的 permanent worktree。Permanent worktrees 不会被自动删除，并且你可以从同一个 permanent worktree 启动多个 threads。

How Codex manages worktrees for you

Codex 会在下面位置创建 worktrees：

$CODEX_HOME/worktrees

starting commit 是你启动 thread 时所选 branch 的 HEAD commit。如果你选择了带 local changes 的 branch，uncommitted changes 也会被应用到 worktree。

worktree 不会作为 branch checkout，而是处于 detached HEAD 状态。这样 Codex 可以创建多个 worktrees，而不污染你的 branches。

Branch limitations

假设 Codex 在 worktree 上完成了一些工作，然后你用 Create branch here 创建了 feature/a branch。现在你想在 local checkout 里试这个 branch。如果直接 checkout，会收到类似错误：

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

要解决它，需要先在 worktree 上 checkout 到 feature/a 之外的另一个 branch。

如果你计划在 local checkout 中 checkout 这个 branch，应该用 Handoff 把 thread 移入 Local，而不是试图在两个地方同时 checkout 同一个 branch。

为什么有这个限制：

Git 会阻止同一个 branch 同时在多个 worktrees 中 checkout，因为 branch 表示一个 mutable reference，也就是 refs/heads/<name>，含义是某个 working tree 的当前 checked-out state。

branch 被 checkout 时，Git 会把它的 HEAD 视为被那个 worktree 拥有，并期望 commits、resets、rebases、merges 等操作以明确、串行的方式推进这个 reference。如果允许多个 worktrees 同时 checkout 同一个 branch，就会导致哪个 worktree 的操作更新 branch reference 变得模糊，可能造成 lost commits、inconsistent indexes 或不清楚的 conflict resolution。

通过强制 one-branch-per-worktree 规则，Git 保证每个 branch 只有一个 authoritative working copy，同时其他 worktrees 仍可通过 detached HEADs 或 separate branches 安全引用相同 commits。

清理 worktree

Worktrees 可能占用大量磁盘空间。每个 worktree 都有自己的一套 repository files、dependencies、build caches 等。因此，Codex App 会尝试把 worktree 数量控制在合理范围。

默认情况下，Codex 保留最近 15 个 Codex-managed worktrees。你可以在 settings 中修改这个 limit，或者关闭 automatic deletion，自己管理 disk usage。

Codex 会尽量避免删除仍然重要的 worktrees。Codex-managed worktrees 在这些情况下不会被自动删除：

A pinned conversation is tied to it
The thread is still in progress
The worktree is a permanent worktree

Codex-managed worktrees 会在这些情况下自动删除：

你 archive 了 associated thread。
Codex 需要删除 older worktrees，以保持在 configured limit 内。

删除 Codex-managed worktree 前，Codex 会保存该 worktree 上工作的 snapshot。如果你在 worktree 被删除后打开关联 conversation，会看到 restore 选项。