Appearance
Worktrees 让 Codex App 在同一个 Git 仓库里同时运行多个独立任务而不互相干扰——每个 Worktree 有自己的文件副本，共享同一个 .git 元数据。你可以在前台（Local）工作的同时，让 Codex 在后台 Worktree 里处理其他任务。完成后通过 Handoff 把工作切回 Local 继续。本文覆盖 Worktree 的核心概念、创建流程、Handoff 机制和磁盘清理策略。
Codex App Worktrees：并行隔离工作环境
Worktrees 让你可以在同一个 Git 仓库里并行运行多个 Codex 任务，彼此完全隔离。它基于 Git 内置的 git worktree 机制，要求项目必须是 Git 仓库。
核心概念
| 术语 | 含义 |
|---|---|
| Local | 你正常工作的主 checkout |
| Worktree | 由 Codex 创建的独立副本，有自己的文件，但共享 .git 元数据 |
| Handoff | 在 Local 和 Worktree 之间移动线程（含代码）的操作，Codex 自动处理 Git 操作 |
适合在 Worktree 里做的事：
- 后台长任务不阻塞前台
- Automations 的隔离运行
- 多功能并行开发
- 随时把工作切回 Local 做最终检查
快速开始
- 新建线程时，在输入框下方选择 Worktree（而不是 Local）
- 可选：选择一个本地环境（setup 脚本）
- 在下方选择基础分支（可以是
main、功能分支，或带未暂存改动的当前分支） - 发送任务，Codex 在 detached HEAD 状态的 Worktree 里工作
- 完成后选择：
- Create branch here：把 Worktree 变成一个分支，推送 PR
- Hand off：把线程移到 Local 继续检查
Local 和 Worktree 之间的切换
选项 1：在 Worktree 上完成工作
点击线程头部的 Create branch here，给 Worktree 创建一个 Git 分支，然后：
bash
# Codex App 里直接操作，或者用内置终端
git push origin feature/my-branch
# 然后在 GitHub/GitLab 提 PR也可以用线程头部的 Open 按钮在 IDE 里打开 Worktree 目录。
注意：一个分支同一时间只能在一个地方 checkout。Worktree 里创建了
feature/a分支后，你就不能在本地 checkout 这个分支了。
选项 2：Handoff 到 Local
点击线程头部的 Hand off，选择 Local，Codex 自动处理 Git 操作，把代码和线程上下文移到你的主 checkout。
适合：
- 想在常用 IDE 里检查改动
- 要运行本地开发服务器
- 需要在同一环境里做最终验证
反向也支持：从 Local Handoff 到 Worktree，让 Codex 继续在后台工作，你切回前台做别的事。
.gitignore里的文件不会随 Handoff 移动。
Worktree 类型
Codex 管理的 Worktree（默认）
轻量、临时，通常一个线程对应一个 Worktree。Handoff 回 Worktree 时会回到同一个环境继续工作。
永久 Worktree
在侧边栏项目的三点菜单里选择 创建永久 Worktree。永久 Worktree 作为独立项目出现，不会被自动删除，可以从同一个 Worktree 启动多个线程。
自动清理
Worktree 会占用大量磁盘空间（每个都有自己的文件副本、依赖和构建缓存）。
默认保留最近 15 个 Codex 管理的 Worktree，可以在 Settings 里修改这个限制。
不会自动删除的 Worktree：
- 有 Pin 的对话关联
- 线程仍在进行中
- 永久 Worktree
会自动删除的条件：
- 你归档了关联的线程
- 超出数量限制时删除最旧的
删除前，Codex 会保存工作快照。重新打开已被删除 Worktree 的对话时，会提示你是否恢复。
常见问题
Q: 提示 fatal: 'feature/a' is already used by worktree 怎么办？
A: Git 限制同一个分支同时只能在一个地方 checkout。解决方法：在 Worktree 里先切换到另一个分支，或者用 Handoff 把线程移到 Local，而不是尝试在两个地方 checkout 同一个分支。
Q: Worktree 里没有安装好的依赖，Codex 运行会失败吗？
A: 可能会。解决方法：配置一个本地环境（Local Environment），在 Worktree 启动时自动运行 setup 脚本安装依赖。详见 本地环境配置。
Q: 我能指定 Worktree 的存储位置吗？
A: 目前不行。Codex 统一把 Worktree 创建在 $CODEX_HOME/worktrees 下以便统一管理，这个路径不可自定义。