# Claude Code Worktrees 并行工作区

> Claude Code worktree 的 --worktree 启动、base branch、PR worktree、.worktreeinclude、子代理隔离、清理策略和非 Git VCS hooks。

URL: https://docs.passion8.cc/docs/claude-code/worktrees
Language: zh-CN
Publisher: Passion8

Git worktree 是同一个仓库历史和远端下的另一个工作目录。Claude Code 用它来隔离并行会话:一个终端做新功能,另一个终端修 bug,文件改动不会直接撞在同一个 checkout 里。




Worktree 隔离的是文件系统改动。要把工作拆给不同 agent,看 [子代理](https://docs.passion8.cc/docs/claude-code/subagents);要管理会话恢复、命名和切换,看 [会话管理](https://docs.passion8.cc/docs/claude-code/sessions)。




## 何时使用

| 场景 | 建议 |
| --- | --- |
| 两个 Claude 会话同时改同一仓库 | 用 `--worktree` 各自隔离 |
| 想基于远端默认分支干净开工 | 默认 `--worktree <name>` |
| 子代理可能编辑文件 | 给 agent 设置 `isolation: worktree` |
| 本地还有未推送基础改动 | 设置 `worktree.baseRef` 为 `head` |
| 需要带上 `.env.local` | 用 `.worktreeinclude` 复制 gitignored 文件 |

大型 Monorepo 可以用 `worktree.sparsePaths` 和 `symlinkDirectories` 减少每个工作区的检出范围,配置示例见 [大型代码库与 Monorepo](https://docs.passion8.cc/docs/claude-code/large-codebases)。

Claude Code 桌面端的新并行 session 会自动创建 worktree。本文主要讲 CLI。

## 启动 worktree 会话

传 `--worktree` 或 `-w` 即可创建隔离工作区并在里面启动 Claude。

```bash
claude --worktree feature-auth
```

默认位置和分支名:

| 项 | 默认值 |
| --- | --- |
| 目录 | 仓库根目录下 `.claude/worktrees/<name>/` |
| 分支 | `worktree-<name>` |

再开一个终端可以启动第二个隔离会话:

```bash
claude --worktree bugfix-123
```

省略名称时,Claude Code 会生成一个随机名称:

```bash
claude --worktree
```

会话中也可以直接要求 Claude “work in a worktree”。Claude 会通过 `EnterWorktree` 工具创建并进入 worktree。已经进入后,它还可以切换到 `.claude/worktrees/` 下的另一个 worktree,原 worktree 会留在磁盘上。




第一次在某个目录交互式使用 `--worktree` 前,先直接运行一次 `claude` 并接受 workspace trust。否则 `--worktree` 会退出并提示你先信任该目录。`claude -p --worktree` 这类非交互运行会跳过 trust check。




建议把 Claude 自动创建的目录加入 `.gitignore`:

```gitignore
.claude/worktrees/
```

## Base branch

默认情况下,新 worktree 从仓库默认分支 `origin/HEAD` 创建,相当于基于远端干净状态开一条新分支。如果没有远端或 fetch 失败,会回退到当前本地 `HEAD`。

如果你希望 worktree 继承当前分支的未推送提交和开发状态,在 settings 里设置:

```json title=".claude/settings.json"
{
  "worktree": {
    "baseRef": "head"
  }
}
```

`baseRef` 只接受两个值:

| 值 | 含义 |
| --- | --- |
| `fresh` | 默认,优先从 `origin/HEAD` 创建 |
| `head` | 从当前本地 `HEAD` 创建 |

要基于 GitHub PR 创建 worktree,传 PR 号并加 `#`,或传完整 PR URL:

```bash
claude --worktree "#1234"
```

Claude Code 会从 `origin` fetch `pull/<number>/head`,并在 `.claude/worktrees/pr-<number>` 创建工作区。

## 复制本地配置

Worktree 是一个新 checkout,主目录里的未跟踪文件不会自动出现。常见例子是 `.env`、`.env.local`、本地 secrets 文件。

在仓库根目录添加 `.worktreeinclude`,可让 Claude 创建 worktree 时复制指定 gitignored 文件。语法沿用 `.gitignore` 风格。

```text title=".worktreeinclude"
.env
.env.local
config/secrets.json
```

重要边界:

| 规则 | 说明 |
| --- | --- |
| 只复制 gitignored 文件 | 已被 Git 跟踪的文件不会被复制 |
| 适用于多种入口 | `--worktree`、subagent worktree、桌面端并行 session |
| 自定义 `WorktreeCreate` hook 时不处理 | 非 Git 或自定义创建逻辑要自己复制 |




不要把真实 API Key 提交到仓库。接入 Passion8 时,更稳的是把 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN` 放在用户级 settings 或本机环境变量里;只有确实依赖项目 `.env` 时才用 `.worktreeinclude` 复制。




## 子代理 worktree 隔离

子代理也可以在临时 worktree 里运行,这样多个 agent 并行修改文件时不会互相覆盖。

```markdown title=".claude/agents/fixer.md"
---
name: fixer
description: 修复独立问题。需要改文件时使用隔离 worktree。
tools: Read, Grep, Glob, Edit, Bash
isolation: worktree
---

你在隔离 worktree 中工作。保持改动聚焦,完成后说明变更文件和验证结果。
```

也可以直接要求 Claude “use worktrees for your agents”。子代理 worktree 使用和 `--worktree` 相同的 base branch 策略:默认从远端默认分支开始,除非 `worktree.baseRef` 设为 `head`。

如果子代理结束时没有改动,临时 worktree 会自动移除。产生改动时,Claude 会保留必要信息供你处理。

## 清理策略

退出 `--worktree` 会话时,Claude Code 会根据改动状态决定是否清理:

| 状态 | 行为 |
| --- | --- |
| 没有未提交改动、未跟踪文件和新提交 | 自动删除 worktree 和分支;如果会话有名称,会先询问是否保留 |
| 有未提交改动、未跟踪文件或新提交 | 询问保留还是删除;删除会丢弃这些内容和分支 |
| `-p` 非交互运行 | 不自动清理,需要手动 `git worktree remove` |

子代理和后台 session 创建的 worktree 会被周期清扫。只有满足这些条件才会删除:

- 超过 `cleanupPeriodDays`
- 没有未提交改动
- 没有未跟踪文件
- 没有未推送提交

你用 `--worktree` 显式创建的 worktree 不会被这个后台清扫自动删除。

运行中的 agent worktree 会被 `git worktree lock` 锁住,防止并发清理误删。agent 完成后锁会释放。

## 手动管理

需要完全控制位置、分支或已有分支时,直接使用 Git 命令。

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

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

进入手动 worktree 后启动 Claude:

```bash
cd ../project-feature-a
claude
```

常用维护命令:

| 命令 | 作用 |
| --- | --- |
| `git worktree list` | 列出所有 worktree |
| `git worktree remove ../project-feature-a` | 删除干净 worktree |
| `git worktree remove --force ../project-feature-a` | 强制删除含未提交改动的 worktree |

每个 worktree 都是独立工作目录。依赖安装、虚拟环境、生成文件、数据库迁移等项目初始化步骤,需要按项目实际情况重新处理。

## 非 Git 版本控制

Claude Code 默认用 Git worktree。SVN、Perforce、Mercurial 或其他版本控制系统,可以通过 `WorktreeCreate` 和 `WorktreeRemove` hooks 自定义创建和清理逻辑。

```json title=".claude/settings.json"
{
  "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\"'"
          }
        ]
      }
    ]
  }
}
```

这个 hook 从 stdin 读取 worktree 名称,创建工作目录,并把目录路径打印给 Claude Code。使用自定义 `WorktreeCreate` 时,默认 Git 创建逻辑会被替换,`.worktreeinclude` 也不会自动处理;需要在 hook 脚本里自己复制本地配置。

## 常见误区

| 误区 | 结果 | 修正 |
| --- | --- | --- |
| 以为 worktree 会自动带上 `.env` | 新会话缺少本地密钥或环境变量 | 用用户级 settings、shell env 或 `.worktreeinclude` |
| 主分支有未推送基础改动,却默认开 worktree | 新 worktree 从远端默认分支开始,看不到本地基础提交 | 设置 `worktree.baseRef: "head"` |
| 把 `.claude/worktrees/` 提交进仓库 | 大量隔离 checkout 变成未跟踪文件 | 加入 `.gitignore` |
| 用 `-p --worktree` 后期待自动删除 | 非交互模式没有退出提示 | 手动 `git worktree remove` |
| 多个 agent 直接改同一 checkout | 文件互相覆盖或上下文失效 | 对可写子代理使用 `isolation: worktree` |

## 官方参考

- [Run parallel sessions with worktrees](https://code.claude.com/docs/en/worktrees.md)
- [Create custom subagents](https://code.claude.com/docs/en/sub-agents.md)
- [Claude Code settings](https://code.claude.com/docs/en/settings.md)
- [Hooks reference](https://code.claude.com/docs/en/hooks.md)
- [Git worktree documentation](https://git-scm.com/docs/git-worktree)