用 Worktree 运行并行会话

将并行的 Claude Code 会话隔离到不同的 git worktree 中，避免更改互相冲突。涵盖 --worktree 标志、子智能体隔离、.worktreeinclude、清理机制，以及非 git 版本控制的钩子。

git worktree 是一个拥有自己文件和分支的独立工作目录，与你的主检出共享同一份仓库历史和远程仓库。让每个 Claude Code 会话在各自的 worktree 中运行，意味着一个会话中的编辑永远不会触及另一个会话中的文件，因此你可以在一个终端中让 Claude 构建功能，同时在另一个终端中修复 bug。

本页介绍 CLI 中的 worktree 隔离机制。以下内容均假定使用 git 仓库。关于其他版本控制系统，请参阅非 git 版本控制。桌面应用会自动为每个新会话创建一个 worktree。

Worktree 是并行运行 Claude 的多种方式之一。它们隔离文件编辑，而子智能体和智能体团队则协调工作本身。要比较这些方式，请参阅并行运行智能体，或直接跳到用 Worktree 隔离子智能体了解如何将 worktree 与子智能体结合使用。

在 Worktree 中启动 Claude

传入 --worktree 或 -w，即可创建一个隔离的 worktree 并在其中启动 Claude。默认情况下，该 worktree 会在你的仓库根目录下的 .claude/worktrees/<value>/ 中创建，并使用一个名为 worktree-<value> 的新分支：

claude --worktree feature-auth

要把 worktree 放到其他位置，可配置一个 WorktreeCreate 钩子。在另一个终端中用不同的名称再次运行该命令，即可启动第二个隔离的会话：

claude --worktree bugfix-123

如果省略名称，Claude 会生成一个，例如 bright-running-fox：

claude --worktree

你也可以在会话中让 Claude “在 worktree 中工作”，它会用 EnterWorktree 工具创建一个。一旦进入某个 worktree，Claude 可以通过用目标路径调用 EnterWorktree，直接切换到 .claude/worktrees/ 下的另一个 worktree。之前的 worktree 会原样保留在磁盘上。

从 v2.1.198 开始，进入或退出某个 worktree 也会把会话记录迁移到该目录的项目存储中，方式与 /cd 相同，因此之后 /desktop 和 --resume 都能在那里找到该会话。由 WorktreeCreate 钩子创建的 worktree 不受此影响，会话记录仍保留在启动目录中。

在某个目录中首次交互式使用 --worktree 之前，请先在该目录中运行一次 claude，以接受工作区信任对话框。如果尚未接受信任，--worktree 会以错误退出，并提示你先在该目录中运行 claude。用 -p 进行的非交互式运行会跳过信任检查，因此 claude -p --worktree 无需该步骤即可继续执行。

如果 Claude Code 在启动时无法进入该 worktree 目录——例如因为某个 WorktreeCreate 钩子打印的内容不是它创建的目录，或者因为该目录在设置完成后被删除——Claude Code 会打印一条说明路径的错误并以退出码 1 退出。在 v2.1.205 之前，这会导致会话崩溃，而在使用 -p 时会先卡顿约 30 秒，再以退出码 0 退出。

从主检出以项目范围安装的插件，也会加载到同一仓库的各个 worktree 中，因此你不需要为每个 worktree 重新安装它们。无论你是用 --worktree 还是用 git worktree add 创建该 worktree，都是如此。需要 Claude Code v2.1.200 或更高版本。

选择基础分支

Worktree 会从你仓库的默认分支 origin/HEAD 分出，因此它们从一份与远程仓库一致的干净树开始。如果没有配置远程仓库，或获取失败，该 worktree 会回退到你当前本地的 HEAD。要始终从本地 HEAD 分出，可在设置中将 worktree.baseRef 设为 "head"。将 baseRef 设为 "head" 会让新的 worktree 带上你尚未推送的提交和特性分支状态，这在隔离需要处理进行中工作的子智能体时很有用。该设置只接受 "fresh" 或 "head"，不接受任意的 git ref：

{
  "worktree": {
    "baseRef": "head"
  }
}

要从特定的 pull request 分出，传入以 # 为前缀的 PR 编号，或一个完整的 GitHub pull request 网址。Claude Code 会从 origin 获取 pull/<number>/head，并在 .claude/worktrees/pr-<number> 创建该 worktree：

claude --worktree "#1234"

要完全控制 worktree 的创建方式，可配置一个 WorktreeCreate 钩子，它会完全取代默认的 git worktree 逻辑。

将被 gitignore 的文件复制到 Worktree 中

一个 worktree 是一份全新的检出，因此主仓库中未跟踪的文件（例如 .env 或 .env.local）不会存在于其中。要让 Claude 创建 worktree 时自动复制这些文件，请在项目根目录添加一个 .worktreeinclude 文件。

该文件使用 .gitignore 语法。只有同时匹配某个模式、且已被 gitignore 的文件才会被复制，因此已跟踪的文件永远不会被重复复制。

以下这份 .worktreeinclude 会将两个环境文件和一份密钥配置复制到每个新的 worktree 中：

.env
.env.local
config/secrets.json

这适用于用 --worktree 创建的 worktree、子智能体 worktree，以及桌面应用中的并行会话。

用 Worktree 隔离子智能体

子智能体可以在自己的 worktree 中运行，避免并行编辑发生冲突。可以让 Claude “为你的智能体使用 worktree”，或在自定义子智能体的 frontmatter 中加入 isolation: worktree 使其永久生效。每个子智能体都会获得一个临时的 worktree，当该子智能体在未做任何更改的情况下完成时会自动移除。

子智能体的 worktree 使用与 --worktree 相同的基础分支，因此除非 worktree.baseRef 被设为 "head"，否则它们会从你仓库的默认分支分出。

清理 Worktree

当你退出一个 worktree 会话时，清理方式取决于你是否做了更改：

• 没有未提交的更改、没有未跟踪的文件，也没有新提交：该 worktree 及其分支会被自动移除。如果该会话有名称，Claude 会改为提示你，以便你可以保留该 worktree 供之后使用
• 存在未提交的更改、未跟踪的文件，或新提交：Claude 会提示你保留还是移除该 worktree。保留会保存该目录和分支，方便你之后回来继续；移除会删除该 worktree 目录及其分支，同时丢弃任何未提交的更改、未跟踪的文件和提交
• 非交互式运行：与 -p 一起用 --worktree 创建的 worktree 不会自动清理，因为没有退出提示。请用 git worktree remove 移除它们

Claude 为子智能体和后台会话创建的 worktree，一旦超过你设置的 cleanupPeriodDays，且没有未提交的更改、未跟踪的文件或未推送的提交，就会被自动移除。你用 --worktree 创建的 worktree 永远不会被这项清理扫描移除。

当一个智能体正在运行时，Claude 会对其 worktree 运行 git worktree lock，使并发的清理无法移除它。该锁会在该智能体完成时释放。要清理一个被清理扫描保留下来的 worktree，请运行 git worktree remove；如果该 worktree 有未提交的更改或未跟踪的文件，请加上 --force。

在 Windows 上，移除某个 worktree 之前，Claude Code 会将其内部任意深度的每个 NTFS 联接点或目录符号链接都当作一个链接条目移除，因此移除该 worktree 不会删除该链接所指向的文件。在 v2.1.205 之前，Claude Code 只会将顶层链接当作链接条目移除，如果某个联接点嵌套在子目录中，移除该 worktree 可能会删除该链接指向的、worktree 之外目录的内容。

手动管理 Worktree

要完全控制 worktree 的位置和分支配置，可以直接用 Git 创建 worktree。当你需要检出某个特定的既有分支，或将 worktree 放在仓库之外时，这很有用。

在新分支上创建一个 worktree：

git worktree add ../project-feature-a -b feature-a

从一个既有分支创建一个 worktree：

git worktree add ../project-bugfix bugfix-123

在该 worktree 中启动 Claude：

cd ../project-feature-a && claude

列出你的 worktree：

git worktree list

用完后移除它：

git worktree remove ../project-feature-a

关于完整的命令参考，请参阅 Git worktree 文档。请记得在每个新的 worktree 中初始化你的开发环境：安装依赖、搭建虚拟环境，或执行你项目搭建所需的任何其他步骤。

非 git 版本控制

Worktree 隔离默认使用 git。对于 SVN、Perforce、Mercurial 或其他系统，请配置 WorktreeCreate 和 WorktreeRemove 钩子，提供自定义的创建和清理逻辑。由于该钩子会取代默认的 git 行为，当你使用 --worktree 时，.worktreeinclude 不会被处理。请在你的钩子脚本中自行复制任何本地配置文件。

以下这个 WorktreeCreate 钩子从 stdin 读取 worktree 名称，检出一份全新的 SVN 工作副本，并打印目录路径，以便 Claude Code 将其用作该会话的工作目录：

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

将其与一个 WorktreeRemove 钩子配合使用，可在会话结束时进行清理。关于输入模式和一个移除示例，请参阅钩子参考。

另请参阅

Worktree 负责文件隔离。以下相关页面介绍如何将工作委派到这些隔离的检出中，以及如何在你创建的会话之间切换：

• 子智能体：在一个会话内将工作委派给隔离的智能体
• 智能体团队：自动协调多个 Claude 会话
• 管理会话：命名、恢复对话，并在对话之间切换
• 桌面端并行会话：桌面应用中基于 worktree 的会话