使用 worktrees 运行并行会话

​

在 worktree 中启动 Claude

claude --worktree feature-auth

​

设置 worktree 环境

​

要求 Claude 创建 worktree

​

清理 worktrees

• worktree 是干净的：对于未命名的会话，Claude 会自动删除 worktree 及其分支。命名的会话会提示您，以便您可以稍后保留 worktree
• worktree 中有工作：Claude 提示您保留或删除 worktree。保留会保留目录和分支，以便您稍后可以返回。删除会删除 worktree 目录及其分支，以及其中的所有工作
• worktree 的状态无法验证：当 Claude Code 无法计算 worktree 的更改或无法检查其子模块检出时，它会提示您而不是自动删除 worktree。提示会说明它无法检查的内容

​

恢复 worktree 会话

• 启动目录：从主检出或存储库的另一个目录恢复。Claude Code 会重新进入它使用 git 在 .claude/worktrees/ 下创建的 worktree，即使您从其内部启动。当您从任何其他 worktree 内启动时，Claude Code 只有在能够从那里为其担保时才会重新进入它：一个是其自己的存储库的 worktree、一个没有 git 元数据的 worktree，或从您使用 git worktree add 创建的 worktree 的子目录启动会拒绝，因此从主检出启动这些。
• --fork-session：分叉的会话在您启动 Claude 的目录中启动，Claude Code 会保持原始会话的 worktree 不变。
• 已删除的 worktree：如果 worktree 目录不再存在，Claude Code 会在您启动 Claude 的目录中恢复会话。它告诉您 worktree 已消失并清除会话的 worktree 绑定。

​

Claude Code 如何强制隔离

• 文件编辑：Claude Code 阻止针对主检出中的路径的 Edit、Write 或 NotebookEdit。
• 命令工作目录：Claude Code 阻止其工作目录解析为主检出的 Bash、PowerShell 或 Monitor 命令，或其工作目录它无法验证保持在其外的命令。
• Git 重定向：Claude Code 阻止将 git 重定向到主检出的 Bash 或 Monitor 命令。重定向可以通过 git -C、--git-dir、GIT_DIR 或 GIT_WORK_TREE 变量，或在运行 git 之前 cd 到主检出来进行。
• 命令形状：当 Claude Code 无法从命令文本验证命令运行的任何 git 保持在 worktree 内时，它会阻止 Bash 或 Monitor 命令。例如，当命令名称在运行时计算、语法无法解析，或当诸如 ${!name} 或 ${ command; } 之类的扩展可能运行文本中未明确说明的命令时，就会发生这种情况。Claude Code 告诉 Claude 如何重写被拒绝的命令，例如将其分割成普通的单独命令。您无法关闭此检查。

​

使用 worktrees 隔离子代理

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

清理子代理和后台会话 worktrees

• worktree 仍然保留工作：已更改或未跟踪的文件，或未推送的提交。
• worktree 中已检出的子模块保留已更改或未跟踪的文件，或 Claude Code 无法检查 worktree 的子模块。此检查需要 Claude Code v2.1.274 或更高版本。
• Claude Code 无法确定存储库配置定义的过滤驱动程序，或在其中找到它无法关闭的设置，或四种也阻止 worktree 创建的情况中的任何一种适用。
• worktree 属于您未后台的 --worktree 会话，无论其年龄如何。
• 您自己使用 git worktree add 创建了 worktree，即使您随后在其中运行了 --worktree <name> 会话并后台了该会话。

​

自定义 worktree 创建

​

选择基础分支

• "fresh"（默认）：从存储库在远程上的默认分支分支，通常是 main，因此 worktree 从与远程匹配的干净树开始。
• "head"：从您当前的本地 HEAD 分支，因此 worktree 携带您未推送的提交和功能分支状态。当隔离需要在进行中的工作上操作的子代理时使用此选项。在 worktree 内，"head" 解析为该 worktree 的 HEAD，而不是主检出的。

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

​

从拉取请求分支

claude --worktree "#1234"

• github.com：获取 pull/<number>/head
• gitlab.com：获取 merge-requests/<number>/head
• GitHub Enterprise、自管理 GitLab 或任何其他主机：首先尝试 pull/<number>/head，然后尝试 merge-requests/<number>/head

​

将 gitignored 文件复制到 worktrees

.env
.env.local
config/secrets.json

​

重用 worktree 名称

• 它没有未提交的更改或未跟踪的文件。
• 它仍然在 Claude Code 为其创建的分支上。
• 它没有自己的提交，或其拉取请求或合并请求已合并且其远程分支已删除。

• worktree 未通过任何条件。
• Claude Code 无法验证 worktree 的状态。
• worktree.baseRef 是 "head"。
• 名称是拉取请求或合并请求引用。

​

使用 hook 替换 worktree 创建

​

Worktrees 与主检出共享的内容

• 存储库的 .git 目录：worktree 中的 git 命令写入主存储库的共享 .git 目录，沙箱允许这些写入，因此 git commit 等命令可以从启用沙箱的 worktree 内部工作。
• 插件：从主检出在项目范围安装的插件也会在同一存储库的 worktrees 中加载，因此您无需为每个 worktree 重新安装它们。需要 Claude Code v2.1.200 或更高版本。
• 权限批准：在 worktree 会话中为 Bash 命令选择”是，不再询问”会将规则保存到主检出的 .claude/settings.local.json，因此它适用于主检出和存储库的每个其他 worktree，并在 worktree 的删除后存活。在 Windows 和 Claude Code 不使用存储库根的其他情况下，规则与该 worktree 保持一致。在 v2.1.211 之前，在 worktree 中授予的批准被保存在该 worktree 内，不适用于其他地方，并在 worktree 被删除时丢失。请参阅批准保存的位置。
• 未跟踪的 skills、agents 和 commands：当 worktree 检出在其根目录没有 .claude/skills 目录时（例如因为您的 .claude/skills 被 gitignored），Claude Code 会在 worktree 会话中加载主检出的项目 skills。在具有自己的 .claude/skills 目录的 worktree 中，只加载该副本。 相同的读取覆盖也适用于 .claude/agents 和 .claude/commands。对于 skills，读取覆盖需要 Claude Code v2.1.277 或更高版本。

​

手动管理 worktrees

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

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

非 git 版本控制

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

故障排除

​

Claude Code 无法在启动时进入 worktree

​

Worktree 创建在符号链接路径上失败

​

Git LFS 文件在 Claude Code 创建的 worktree 中是指针文件

• Could not read the repository git config to neutralize filter drivers：Claude Code 无法读取存储库的 .git/config，例如因为其权限。修复它并重试。
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline)：在 .git/config 中重命名或删除该过滤驱动程序并重试。
• The repository git config has a conditional include (includeIf)：将 includeIf 在 .git/config 中拉入的设置直接移到该文件中，删除 includeIf，并重试。您全局 git 配置中的 includeIf 不会触发此问题。
• Git was not run: the repository's own git config sets <key>：消息命名一个指向 Git LFS 运行程序的键，例如 lfs.customtransfer.<name>.path 或 lfs.standalonetransferagent。如果该设置是您的，将其移到您的全局 git 配置。如果您不认识它，从存储库的 git 配置中删除它，因为您不信任的工具或检出可能已写入它。一旦键从存储库的配置中消失，重试。

​

Claude Code 拒绝使用 worktree

• 说 launch from the parent checkout 或 Run the resume from the project checkout：您从 worktree 内启动了 Claude Code。改为从主检出启动；worktree 无需重新创建。
• 说 it cannot be resumed or re-entered：此会话中没有任何东西从您启动的地方为 worktree 担保。重新创建它；目录及其工作保留在磁盘上以供手动恢复，当 worktree 有父检出时，从那里恢复也有效。
• 说 it contains the protected checkout：被拒绝的目录是您主检出的父目录，例如您的主目录。不要删除它。更改 worktree 路径，例如您的 WorktreeCreate hook 返回的路径或 EnterWorktree 目标，以便 worktree 不包含检出。
• 说 the protected checkout <path> has a .git entry that could not be examined 或 has git metadata that could not be resolved：问题是主检出的 git 元数据，而不是 worktree 的。不要删除 worktree，忽略消息的尾部建议重新创建它，这不适用于这两个结尾。修复主检出，例如权限问题或 git 对其 .git 的 dubious ownership 拒绝，并重试。
• 说 its recorded path has a network spelling：Claude Code 永远不会恢复到网络路径上的 worktree。在本地路径重新创建 worktree。
• 任何其他结尾：消息命名问题及其修复，例如删除 core.worktree 重定向或重新创建 worktree；遵循它。在删除消息说其 git 身份无法验证的目录之前，首先解决命名的原因，例如 worktree 路径中的符号链接或 git 本身无法运行，因为目录可能是健康的。当您确实重新创建时，从旧目录中拯救您需要的任何更改；它保留在磁盘上。

​

会话在其 worktree 外恢复

• Error: cannot resume into worktree <path>: ...This session was not started. 对于表中显示为 Did not re-enter 的拒绝。Claude Code 在退出前清除 worktree 绑定，错误说明了这一点；下次您恢复对话时，会话在当前目录中继续而不使用 worktree 隔离。在 v2.1.260 之前，Claude Code 没有写入清除的绑定，所以同一恢复的每次重试都以相同的错误失败。 如果您抑制记录写入，清除无法被保存。错误然后说相同的命令将再次被拒绝，并命名 --fork-session 和启动新对话作为在没有 worktree 的情况下继续的方式。
• Error: could not verify worktree <path> for this resume, so the resume was aborted... 对于 Could not verify
• Error: ...The worktree binding is kept. 对于 Could not re-enter
• Notice: the worktree <path> for this session no longer exists... 对于消失的 worktree；Claude Code 打印它并继续会话，如交互式恢复一样

​

另请参阅

• 子代理：在会话内将工作委派给隔离的代理
• 跨会话消息传递：让您的 worktrees 中的会话相互传递发现
• 代理团队：自动协调多个 Claude 会话
• 管理会话：命名、恢复和在对话之间切换
• 桌面并行会话：桌面应用中由 worktree 支持的会话