Claude Code worktree：并行运行多个会话，互不冲突

Claude Code worktree 是什么

git 支持 worktree 已经很多年了：git worktree add 会把一个分支检出到第二个目录，背后用的是同一份 .git 数据。Claude Code 在此基础上更进一步：加上 --worktree（或 -w），它会替你创建 worktree、在里面启动会话、拦截会落到主检出目录的修改，并在你退出时提示清理。

worktree 只隔离文件，别的都不管。想在一个对话里把任务分给多个 worker，用 subagent；各种方式的对比见多个 Claude Code agent。

• 默认位置：仓库根目录下的 .claude/worktrees/<name>/。
• 默认分支名：worktree-<name>。不写名字的话，Claude Code 会自动取一个，比如 bright-running-fox。
• 与检出目录共享的：.git 目录（所以提交和分支在哪里都看得到）、项目范围的插件，以及“不再询问”的权限批准。
• 不共享的：所有被 gitignore 的内容，比如 .env、node_modules 和构建产物。worktree 是一份全新的检出。

worktree 工作流，一步一步来

1. 忽略 worktree 文件夹

   把 .claude/worktrees/ 加进 .gitignore，这样 worktree 里的文件不会在主检出目录里显示为未跟踪。如果你从没在这个仓库里运行过 Claude，先运行一次 claude，接受工作区信任提示；在此之前，交互式的 --worktree 会直接退出。

2. 每个任务开一个会话

   每个任务在一个终端里运行 claude --worktree <name>。用已有的名字再次运行，会重新打开那个 worktree，而不是新建一个。你也可以在会话中途让 Claude “work in a worktree”，它会用 EnterWorktree 工具把自己移进一个 worktree。

   # 两个相互隔离的会话，各开一个终端
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # 从 1234 号 pull request 创建 worktree（# 要加引号）
   claude --worktree "#1234"
   
   # 不让 worktree 出现在 git status 里
   echo ".claude/worktrees/" >> .gitignore

3. 把未跟踪的文件带过去

   在仓库根目录建一个 .worktreeinclude 文件，用 .gitignore 语法列出项目需要的被忽略文件，比如 .env 和 .env.local。Claude Code 会把匹配的文件复制到它创建的每个 worktree 里，包括 subagent 和桌面应用的 worktree。然后在 worktree 里安装依赖，或者在设置里配置好：下面的例子从你当前的工作创建分支，复用同一份 node_modules，并且只检出 web 包。

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. 让会话去干活

   会话处于隔离状态时，Claude Code 会拒绝指向主检出目录的文件编辑、工作目录在主检出目录的命令，以及被重定向到主检出目录的 git 命令（git -C、--git-dir、GIT_DIR）。它不会追踪 cp 这类普通 shell 命令写了什么，所以权限和沙箱依然重要。

5. 像普通分支一样评审和合并

   每个 worktree 都是一个普通分支。在里面提交、推送、开 pull request，像评审队友的代码一样评审它。所有 worktree 共享 .git，所以主检出目录里马上就能看到这个分支。

6. 退出并清理

   退出时，Claude Code 会检查 worktree。未命名会话的 worktree 如果是干净的，会连同分支自动删除；命名会话则会先询问。如果有改动、未跟踪的文件或新提交，它会问你保留还是删除这个 worktree，并打印一条 claude --worktree <name> --resume 命令，方便以后回来继续。

来源：Claude Code 文档，Run parallel sessions with worktrees

Claude Code 的 worktree 设置

以下设置都写在设置文件（~/.claude/settings.json、.claude/settings.json 或 .claude/settings.local.json）的 worktree 下。

Claude Code worktree、切换分支与 git worktree 对比

用 git worktree 手动操作

想用某个已有的分支，或者把文件夹放在仓库之外，就用原生 git；worktree.baseRef 不能指定分支名。Claude Code 依然会和这些 worktree 共享插件和权限批准。

1. 创建 worktree、启动 Claude，用完删除

   把 feature-a 换成新分支名；如果要检出已有的分支，去掉 -b 即可。

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

在 worktree 里运行 subagent 和后台会话

• 让 Claude “use worktrees for your agents”，或者在 .claude/agents/ 里自定义 subagent 的 frontmatter 中加上 isolation: worktree，每个 subagent 就会在各自的临时 worktree 里编辑。
• 没有改动的 subagent worktree 会在 subagent 结束时删除。有改动的会一直保留，直到 cleanupPeriodDays 之后，定期清理能在不丢失工作的前提下把它删掉。
• 后台会话（claude --bg）默认只能在 worktree 里编辑；可以用 claude --bg --worktree 启动，或者把 worktree.bgIsolation 设为 "none"。
• 在桌面应用里，开始会话前先打开输入框下方的 Worktree 开关。

worktree 清理与常见问题

• claude -p --worktree 运行时没有退出提示，所以会留下 worktree。用 git worktree remove 删除；如果 git 提示已锁定，先运行 git worktree unlock。
• Can only use --worktree in a git repository：运行 git init 并做第一次提交，或者为 SVN、Perforce 或 Mercurial 配置 WorktreeCreate hook。
• 如果 Git LFS 是用 --local 安装的，LFS 文件会显示为指针文件：在 worktree 里运行 git lfs pull。
• 当 .claude 或 .claude/worktrees 是符号链接时，Claude Code 不会创建 worktree。
• hook 里的 ${CLAUDE_PROJECT_DIR} 始终指向主检出目录；要拿到 worktree 路径，读取 hook 输入里的 cwd 字段。
• 基准为 "fresh" 且没有自己的提交、或者 PR 已经合并的 worktree，按名字重新打开时会重置到默认分支。

worktree 让会话互不干扰，Crewmark 让它们一直有活干。

worktree 解决了冲突问题，但每个会话仍然要等你输入才会动。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue。

1. 每个 worktree 一名员工

   给每名员工分配各自的 worktree 和岗位，比如同一个仓库里的一名程序员和一名评审，就像多个 Claude Code agent 里那样。

2. 让心跳启动工作

   在工作时间内，每名员工每 15、30 或 60 分钟在同一个对话里醒来一次；参见如何让 Claude Code 主动工作。

3. 分配 issue，评审分支

   把工作放到看板上，每名员工接手一个 issue，在自己的分支上提交，需要你拍板时给你发消息。阅读什么是 AI 员工。

Claude Code worktree 常见问题