Claude Code 的 worktrees 用来把并行会话隔离到不同 git worktree，避免两个会话改到同一批文件。适合一边写功能、一边修 bug，或让子代理在独立工作区里运行；可用 --worktree、worktree.baseRef、.worktreeinclude 和 WorktreeCreate / WorktreeRemove 钩子控制创建、复制和清理。

Claude Code Worktrees 并行会话怎么用

git worktree 会为同一个仓库创建一个独立工作目录，保留相同的仓库历史和远程分支，但每个工作区有自己的文件和分支。Claude Code 把每个会话放进独立 worktree 后，一个会话的编辑不会碰到另一个会话的文件，适合同时开多个终端并行处理任务。

这页讲的是 CLI 里的 worktree 隔离。下面默认你在 git 仓库中使用它。其他版本控制系统的做法看 非 git 版本控制。桌面应用会为每个新会话自动创建 worktree，相关说明见 Desktop 并行会话。

Worktree 只是 Claude Code 并行运行方式之一。它负责隔离文件修改；subagents 和 agent teams 负责协同工作本身。要对比不同方式，可以看 Run agents in parallel，也可以直接跳到 用 worktree 隔离 subagents。

在 worktree 中启动 Claude

给 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 “work in a worktree”，它会通过 EnterWorktree 工具创建一个 worktree。

第一次在某个目录里用 --worktree 之前，要先接受 workspace trust 对话框。做法是在该目录先运行一次 claude。如果还没有接受信任，--worktree 会直接报错并提示你先在这个目录运行 claude，即使和 -p 一起用也一样。

把 .claude/worktrees/ 加到 .gitignore，避免 worktree 内容在主 checkout 里显示成未跟踪文件。

选择 base branch

worktree 默认从仓库的默认分支 origin/HEAD 分叉，这样会从和远程一致的干净树开始。如果没有配置 remote，或者 fetch 失败，worktree 会回退到当前本地 HEAD。如果你想始终从本地 HEAD 分叉，可以在 settings 里把 worktree.baseRef 设成 "head"。这个设置会让新 worktree 带上你尚未 push 的提交和当前 feature 分支状态，适合给需要处理进行中工作的 subagents 隔离环境。这个字段只接受 "fresh" 或 "head"，不支持任意 git ref：

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

如果要从某个 pull request 分叉，可以传 # 开头的 PR 编号，或者完整的 GitHub pull request URL。Claude Code 会从 origin 获取 pull/<number>/head，并把 worktree 创建在 .claude/worktrees/pr-<number>：

claude --worktree "#1234"

如果你想完全控制 worktree 的创建方式，可以配置 WorktreeCreate 钩子，它会完全替代默认的 git worktree 逻辑。

把 gitignored 文件复制到 worktree

worktree 本质上是一次新的 checkout，所以主仓库里的未跟踪文件，比如 .env 或 .env.local，默认不会出现在新 worktree 中。想在 Claude 创建 worktree 时自动复制这些文件，就在项目根目录加一个 .worktreeinclude 文件。

这个文件使用 .gitignore 语法。只有同时满足“匹配规则”并且“本身也被 gitignore”的文件才会被复制，所以被跟踪的文件不会被重复复制。

下面这个 .worktreeinclude 会把两个环境文件和一个 secrets 配置复制到每个新 worktree：

.env
.env.local
config/secrets.json

这个规则同样适用于通过 --worktree 创建的 worktree、subagent worktrees，以及 Desktop 并行会话。

用 worktree 隔离 subagents

subagents 可以运行在自己的 worktree 中，这样并行编辑就不会冲突。你可以直接对 Claude 说“use worktrees for your agents”，也可以在自定义 subagent 的 frontmatter 里永久设置 isolation: worktree。每个 subagent 都会拿到一个临时 worktree；如果它结束时没有产生改动，这个 worktree 会被自动删除。

清理 worktree

退出 worktree 会话时，清理行为取决于你有没有做改动：

• 没有未提交改动、没有未跟踪文件、也没有新提交：worktree 和对应分支会自动删除。如果这个会话有 name，Claude 会先提示你，方便你把 worktree 保留到以后
• 存在未提交改动、未跟踪文件，或有新提交：Claude 会提示你保留还是删除 worktree。选择保留会保留目录和分支，之后可以继续回来；选择删除会删除 worktree 目录和分支，并丢弃所有未提交改动、未跟踪文件和提交
• 非交互运行：--worktree 和 -p 一起使用时，不会在退出时自动清理，因为没有退出提示。需要手动用 git worktree remove 删除

因崩溃或中断而留下的 subagent worktree，会在启动时被清理，但前提是它们的年龄超过了你的 cleanupPeriodDays 设置，并且没有未提交改动、未跟踪文件，也没有未 push 的提交。你用 --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

用完后移除一个 worktree：

git worktree remove ../project-feature-a

完整命令参考见 Git worktree 文档。记得在每个新 worktree 里重新初始化开发环境，例如安装依赖、配置虚拟环境，或者执行项目需要的初始化步骤。

非 git 版本控制

worktree 隔离默认依赖 git。对于 SVN、Perforce、Mercurial 或其他系统，可以配置 WorktreeCreate 和 WorktreeRemove 钩子 来实现自定义创建和清理逻辑。因为这个钩子会替代默认的 git 行为，所以当你使用 --worktree 时，.worktreeinclude 不会被处理。需要复制本地配置文件的话，请在钩子脚本里自己处理。

下面这个 WorktreeCreate 钩子会从 stdin 读取 worktree 名字，检出一个全新的 SVN working copy，然后把目录路径打印出来，供 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 钩子，在会话结束时做清理。输入 schema 和删除示例见 hooks reference。

另见

worktree 负责文件隔离。下面这些页面讲的是如何把工作分派到这些隔离后的 checkout 里，以及如何在你创建的会话之间切换：

• Subagents：在一个会话里把工作委派给隔离的代理
• Agent teams：自动协调多个 Claude 会话
• Manage sessions：命名、恢复和切换会话
• Desktop parallel sessions：桌面应用里的 worktree 支持会话

常见问题

--worktree 创建后为什么主仓库里会出现未跟踪文件？

通常是因为 .claude/worktrees/ 没有加入 .gitignore。把这个目录忽略掉后，worktree 内容就不会在主 checkout 里显示成未跟踪文件。

为什么 --worktree 一运行就报 workspace trust？

第一次在某个目录使用 --worktree 前，需要先在该目录运行一次 claude 并接受 workspace trust。没有先信任目录时，--worktree 会直接退出并提示你先这样做。

--worktree 和 -p 一起用时为什么不会自动清理？

非交互运行没有退出提示，所以 Claude Code 不会自动清理 worktree。你需要在结束后手动执行 git worktree remove。