↓ 跳过正文

Claude Code AI Agents Git

Claude Code worktree 如何使用:让多个智能体并行工作而不互相覆盖

Claude Code worktree 如何使用:claude -w 的用法,用 .worktreeinclude 带上 .env,node_modules 怎么处理,base ref 和清理,以及在 tmux 里并行跑多个智能体。

Claude Code worktree 如何使用:让多个智能体并行工作而不互相覆盖

要让 Claude Code 在 git worktree 里运行,用 claude -w <名字> 启动就行(完整写法是 --worktree)。Claude Code 会在仓库根目录下创建 .claude/worktrees/<名字>/,并在里面检出一个从远程默认分支切出来的新分支 worktree-<名字>。从这以后,这个会话只能修改这个目录里的文件。在另一个终端里换个名字再跑一遍同样的命令,就有了两个碰不到彼此文件的智能体。坑在于 worktree 是一份全新的检出:.env、node_modules 以及其他被 git 忽略的东西,在你复制或安装之前都不存在。我在 worktree 上踩过的坑,几乎全是这一条。

我平时会同时跑很多个智能体,用上 worktree 是吃了几次亏之后的事。这篇文章讲 claude -w 实际怎么工作(我在 2.1.328 版本上验证过)、.worktreeinclude 是干什么的、node_modules 怎么办、我在 tmux 里怎么摆这些会话,以及什么时候我还是直接用 git worktree add。

这篇文章的八分钟视频版。旁白是英文,配有中文字幕。部分视频素材来自 Coverr。

为什么一个检出目录撑不住多个并行智能体
#

九月的某一天,我在自己做的一个交易平台应用的同一个检出目录里,同时开着五个 Claude Code 会话,结果出了两件事。一个测试配置文件的一行修复,挺过了四次构建失败,等到要提交时却不见了:git commit 说工作区是干净的,文件里装的是另一个会话写的内容。这种丢失的修改,git 里不会留下任何记录:reflog 里没有,stash 里也没有,修改时间看起来也很正常。同一天,一个直接拿工作区构建的部署脚本,差点把另一个会话没做完的改动发到了生产环境。

十月又出了第三件事。一个会话在另一个会话未暂存的改动旁边提交自己的文件,pre-commit 钩子在运行期间把所有未暂存的改动全部 stash 了。另一个会话的修改在这段时间里从磁盘上消失,类型检查随后在它新建的文件上报错,提交也中止了。再加上所有会话都用我的名字提交,git log 根本看不出是谁做了什么。

用 worktree 的理由一句话就能说清:有多个写入者的工作区就是竞态,输的一方连自己输了都不知道。给每个智能体一个独立的工作区,竞态也就没了。

一个仓库,三个工作目录。历史只存一份;文件、HEAD 和 index 每个 worktree 各有一份。

claude -w 的用法和行为
#

在一个用完即删的仓库里真实运行的过程。注意会话结束后锁还在。

下面是官方文档 worktrees 页面里写的内容,加上我自己实际试过的结果:

  • 位置和分支。 claude -w add-search 会在新分支 worktree-add-search 上创建 .claude/worktrees/add-search/。不写名字的话,会自动生成一个像 bright-running-fox 这样的名字。记得把 .claude/worktrees/ 加进 .gitignore,不然主检出目录里会把这些全显示成未跟踪文件。
  • 从哪里切出来(base ref)。 worktree.baseRef 默认是 "fresh",也就是从远程默认分支(通常是 origin/main)切。如果仓库最近 24 小时没 fetch 过,它会先 fetch 一次,最多等五秒。设成 "head" 的话,新 worktree 从你本地当前的 HEAD 切出来,没 push 的提交也会一起带过去。它不能设成某个分支名;想从特定分支创建,就自己用 git worktree add。
  • Pull request。 claude --worktree "#1234" 会 fetch 这个 PR 的 head,然后创建 .claude/worktrees/pr-1234。记得加引号,不然 shell 会把 # 后面当成注释。
  • 信任确认。 在一个从没开过 Claude 的目录里第一次运行交互式的 claude -w,会报错 “Workspace trust not yet accepted”。在那个目录里先普通地运行一次 claude,接受信任对话框就好。claude -p -w 会跳过这一步。
  • 围栏。 会话待在 worktree 里的时候,Claude Code 会拒绝修改主检出目录里的文件,拒绝以主检出目录为工作目录的命令,也拒绝通过 git -C、--git-dir 或 GIT_DIR 指回主检出目录的 git 操作。文档也写明了它拦不住什么:往主检出目录里写东西的 cp 或 shell 重定向,这些检查不会拦。

worktree 和主检出目录共享什么,和不共享什么一样重要。所有 worktree 都写同一个 .git,所以在任何一个里面做的提交和分支,在所有 worktree 里都看得到。项目级插件在哪里都会加载。还有,在 worktree 里回答的 “Yes, and don’t ask again”,会保存到主检出目录的 .claude/settings.local.json 里。所以这条授权对所有 worktree 都生效,删掉当初授权的那个 worktree 之后也还在。这很方便,也多了一个理由:别把密钥写进你要批准的命令里。

清理,以及留下来的锁
#

退出交互式 worktree 会话时,Claude Code 会检查删掉会不会丢东西。没有名字的会话、worktree 又是干净的,会连同分支一起自动删除。有名字的会话会先问你。如果里面还有工作,它会问你要不要保留,之后可以用它打印出来的 claude --worktree <名字> --resume 回来接着干。

非交互运行就不一样了,这也是我试的时候唯一被绊了一下的地方。claude -p 退出时没有确认步骤,所以不会清理。另外,Claude Code 在会话运行期间会给 worktree 加一把 git worktree lock,-p 跑完之后,这把锁还挂着一个已经不存在的进程 ID。上面的录屏里也能看到:git worktree remove 报错 “cannot remove a locked working tree, lock reason: claude session add-search”。文档写的也正是这样:等后面某个会话清理过期锁时会释放,或者先运行 git worktree unlock。知道了就没什么,第一次看到还是会愣一下。

.worktreeinclude:全新检出里没有的文件
#

worktree 里只有被跟踪的文件。想把被 git 忽略的文件也带过去,就在仓库根目录放一个 .worktreeinclude。它用 .gitignore 的语法,Claude Code 只复制既匹配规则、又被 git 忽略的文件,所以被跟踪的文件不会重复复制:

# .worktreeinclude
.env
.env.local
config/secrets.json

它对 Claude Code 用 git 创建的所有 worktree 都生效:claude -w、子智能体的 worktree,以及桌面应用的并行会话。对你自己用 git worktree add 创建的 worktree 不生效;如果你用 WorktreeCreate 钩子替换了创建流程,它会被整个跳过。

我建议别只放 .env,因为最容易被忘掉的被忽略文件,往往不会大声报错。我的应用把部署脚本改成了从干净的 worktree 构建,这样其他会话没提交的修改就永远不会被发出去。可是那个干净的工作区里,缺了某个功能要用的、被 git 忽略的签名证书。镜像照样构建成功,那个功能在生产环境里失败了 13 天,直到脚本改成把证书复制进去、缺一个就报警为止。另一次从 worktree 部署时,缺的是一个被忽略的主题目录,构建是在一个两分钟的导出把工作区弄脏之后才失败的。在把任何要上线的事情交给 worktree 之前,先在主检出目录里运行 git status --short --ignored,想想其中哪些文件是构建要读的。

node_modules:最贵的部分
#

.worktreeinclude 是给小文件用的。它帮不了 node_modules,Claude Code 也没有在 worktree 之间共享它的机制,所以每个需要运行代码的 worktree,都得有自己的一份。

在演示仓库里直接用 git worktree:装依赖之前 84 KB,装完又是完整的 45 MB。

在真实项目里,这些数字就不好看了。我的移动应用仓库在主检出目录旁边有 19 个 worktree。我量了其中 12 个,从 194 MB 到 12 GB 不等,最大的四个正好就是自带 node_modules 的那四个。这周我笔记本的磁盘用到了 96%,要清理的话,就该从它们开始。

几种做法,从简单到巧妙:

  1. 每个 worktree 单独安装。 让智能体一开始就跑 npm install,或者自己装。慢,占磁盘,但不会给你惊喜。
  2. 从 lockfile 相同的检出目录克隆。 在 macOS 上,cp -c -R ../myapp/node_modules . 用的是 APFS 克隆,两边在任何一方改动之前共享数据块。克隆演示里的 45 MB 只用了 0.8 秒。我在真实的 worktree 部署里也用过这个办法。只在 lockfile 一致时克隆,原生构建目录要小心:我的主检出目录里的 iOS Pods 是为比 worktree 分支更旧的 SDK 构建的,所以那部分只能重新安装。
  3. 用 pnpm。 它的包都放在一个 store 里,macOS 上的 pnpm 会先尝试克隆,再尝试硬链接(Linux 和 Windows 上是先硬链接)。在演示里,第二个 worktree 的安装大约五秒就完成了。
  4. 在 WorktreeCreate 钩子里安装。 这个钩子会替换 Claude Code 默认的 git 逻辑,所以可以先 git worktree add,再跑安装。这个我还没试过。如果你要试,记住 .worktreeinclude 不会再被处理,.env 也得在钩子里自己复制。

在 tmux 里跑并行智能体
#

我本来就住在 tmux 里(布局写在我每天怎么用 Claude Code那篇里),所以 worktree 直接就能放进去:一个 worktree 一个窗口,或者一个窗格。下面是同时启动的三个智能体,每个都被要求改同一个文件:

三个智能体,一个文件,没有冲突。主检出目录保持干净,每个改动都在自己的分支里等着。

其中两个同时改了 src/index.js,谁也没察觉到对方,因为它们各自的 src/index.js 在磁盘上是不同的文件。主检出目录也一直是干净的。最后留给你的,是三个要审查、要合并的分支,这是 worktree 替你做不了的事:两个智能体改了同一行,照样会有合并冲突。只不过它不再是悄无声息的覆盖,而是出现在你看得见的合并环节。

在 VS Code 里,worktree 就是一个普通文件夹:code .claude/worktrees/add-search 会在一个新窗口里打开它,用的是它自己的分支。

worktree 是一张快照
#

worktree 也会过时。11 月 19 日,一个两三天前就准备好的 worktree 发出了一次 OTA 更新,结果悄悄回退了这期间从别处发出的两个修复。当天就发现并替换掉了,但 worktree 隔离得太好,问题恰恰在这:它从来没看到过那两个修复。其实一行 git 命令就能在发布前发现:

只要不是刚切出来的 worktree,发布前都该跑一下这个检查。

baseRef: "fresh" 能让新 worktree 保持最新。可没有什么能让旧的 worktree 保持最新,所以从旧 worktree 发布之前,先检查一下。

子智能体和钩子
#

要得到这种隔离,并不需要给每个智能体开一个终端。在 front matter 里写上 isolation: worktree 的自定义子智能体,每次都会在自己的临时 worktree 里运行:

---
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.

这是文档里的例子。子智能体没做任何改动就结束的话,它的 worktree 会被删除;有改动的会一直保留,直到定期清理能在不丢工作的前提下删掉它。有个细节:在 .claude/worktrees/ 下的 worktree 里运行的子智能体,指令来自你的主对话,不会加载 worktree 根目录里的 CLAUDE.md。

WorktreeCreate 和 WorktreeRemove 钩子会整个替换 git 逻辑。它们本来是给其他版本控制系统用的,或者用来把 worktree 放在 .claude/worktrees/ 以外的地方,不过像上面那样的安装步骤,也可以放在这里。

什么时候直接用 git worktree add 更好
#

坦白说,我那个应用仓库里的 .claude/worktrees 目录是空的。它的 19 个 worktree 全是用普通的 git worktree add 建的,全是最近一个月建的,一半处于 detached HEAD 状态。笔记本上其他仓库里还有 40、40、18、10、3、2、2 个。而且大多数不是我建的:这台笔记本上的 638 份 Claude Code 对话记录里,有 85 份是智能体在运行 git worktree add,加起来一共 336 次。

直接用 git 更好的情况:

  • 需要某个已有的分支时, 比如为热修复保留的发布分支。baseRef 做不到。
  • 只想发出一个修复时。 其他会话已经往 main 提交了还没部署的工作,所以我在生产环境正在运行的那个提交上建了一个 detached worktree,只把我的修复 cherry-pick 进去,从那里部署。这样发出去的就只有这一个修复。
  • 自己给智能体写任务说明时。 在一个仓库上同时启动好几个智能体时,我给每个的说明里都会写:用 git worktree add --detach "$TMPDIR/<task>-wt" refs/remotes/origin/main 建自己的 worktree,用 git push origin HEAD:main 推送,有冲突就 rebase。
  • 想让它一直留着时。 Claude Code 的清理永远不会删除你用 git worktree add 自己建的 worktree。

claude -w 更适合手动开会话、又想把建分支、复制 .env、围住主检出目录和清理都交给它的时候。两者混着用完全没问题:不管用哪种方式创建,Claude Code 都把它当作 worktree 对待,上面说的和主检出目录的共享也一样。

简短总结
#

每个并行会话用一个 claude -w <名字>,并把 .claude/worktrees/ 加进 .gitignore。.worktreeinclude 里不要只写 .env,要把构建需要的被忽略文件都列进去。提前想好 node_modules 怎么办:每个 worktree 单独装、克隆,还是用 pnpm。用 -p 跑完之后,可能会留下一把需要 git worktree unlock 的锁。从不是刚切出来的 worktree 发布之前,先确认它包含了线上已有的内容。worktree 能防止智能体互相覆盖文件,却防不了它们意见不合,最后审查那三个分支的,还是你自己。

延伸阅读
#

本站:

站外: