Claude Code 学习站
Mingyu's Library

学习站 / 系统课程 / D11

D11 · Worktrees 与 agent view

并行的另一维度:用 git worktree 把每个会话隔离在独立工作副本里改文件,再用 agent view 一屏看住所有后台会话。

D10 的 subagents 解决「工作怎么拆」,今天解决「文件怎么不打架」:worktree 给每个并行会话一份独立的文件副本,agent view 则是这些会话的总控台——谁在跑、谁在等你、谁完工了,一眼看清。

为什么这天学这个

D10 讲了 subagents:把一个任务拆给多个 agent 并行推进,那是「工作的并行」。但只要它们都在同一个工作目录里写文件,并行就有天花板——两个会话同时改同一个文件,后写的覆盖先写的。本课补上另一个维度,「文件的并行」:官方官方文档明确把几种并行方式分了工——worktree 负责隔离文件改动,subagents 和 agent teams 负责组织工作本身,两者可以叠加使用。

这课也是 D12 agent teams 的地基:多个会话协同的前提是各有各的地盘。而当后台会话多起来,你需要一个面板看住它们——这就是本课第二个主角 agent view。学完想直接上手多会话并行的完整套路,可接着读 Tip B2:用 worktrees 跑并行会话,以及 Tip B1:多会话还是多 agent。

概念讲清楚

git worktree:一个仓库,多张工作台

官方git worktree 是一个独立的工作目录:有自己的文件和自己的分支,但和主 checkout 共享同一份仓库历史和远程。每个 Claude Code 会话跑在自己的 worktree 里,一个会话的编辑就永远碰不到另一个会话的文件——一边开发新功能,另一边同时修 bug。

本站观点类比:仓库的 .git 是图书馆的馆藏,主 checkout 是你常坐的那张阅览桌。worktree 就是多摆几张桌子,每张桌子摊开不同分支的文件——桌面互不干扰,但书都借自同一个馆藏,还书(commit)也都归回同一个馆藏。

claude(终端 1) claude --worktree feature-auth claude --worktree bugfix 主 checkout 分支:main 目录:仓库根 worktree feature-auth 分支:worktree-feature-auth .claude/worktrees/feature-auth/ worktree bugfix 分支:worktree-bugfix .claude/worktrees/bugfix/ 文件与分支:各自独立,改动互不可见 共享的 .git(提交历史 · 分支 · 远程 origin) worktree 里的 commit 写进同一个 .git,主 checkout 立即可见
三个并行会话:文件各改各的,历史却全体共享——这是 worktree 隔离与合并都简单的原因。

误区:worktree 不是 clone

本站观点常见误解是「worktree 就是再 clone 一份」。区别在共享什么:clone 出来的是另一个完整仓库,历史独立,要靠 push/pull 来回同步;worktree 只复制工作文件,官方它里面的 git 命令直接写入主仓库共享的 .git 目录,所以在 worktree 里 commit,主 checkout 立刻能看到那个分支——合并回主分支就是一次本地 merge 或一个 PR,不存在「跨仓库搬运」。除了 .git,worktree 还和主 checkout 共享项目级 plugins 和已保存的权限批准(「Yes, don't ask again」写回主 checkout 的 .claude/settings.local.json,全仓库生效)。

用 --worktree 开一个隔离会话

官方带 --worktree(缩写 -w)和一个名字启动,Claude Code 就创建 worktree 并直接在里面开会话。默认位置在仓库根的 .claude/worktrees/<name>/,新分支名为 worktree-<name>;省略名字会自动起一个(如 bright-running-fox)。在另一个终端换个名字再跑一次,就有了第二个互不干扰的会话。

claude --worktree feature-auth   # 终端 1
claude --worktree bugfix         # 终端 2,与终端 1 完全隔离

官方几个常用配套:把 .claude/worktrees/ 加进 .gitignore,免得 worktree 内容在主 checkout 里显示成未跟踪文件;worktree 是全新 checkout,.env 这类被 gitignore 的文件默认不在里面,在项目根加一个 .worktreeinclude 文件(gitignore 语法)可让它们被自动复制进每个新 worktree;新 worktree 默认从仓库默认分支(通常 main)切出,把设置 worktree.baseRef 改成 "head" 则从你当前 HEAD 切出、带上未推送的工作;claude --worktree "#1234" 直接从某个 PR 切出。会话中途也可以口头让 Claude「work in a worktree」,它会用 EnterWorktree 工具建一个。桌面版 app 里每个新会话天然就在自己的 worktree 中。

清理与合并

官方退出交互式 worktree 会话时,Claude 会检查里面有没有「删掉就丢」的东西(改动、未跟踪文件、新 commit):

  • 干净 + 未命名会话:自动删除 worktree 和分支;命名过的会话会先问你,方便留着以后回来。
  • 有工作:询问保留还是删除。保留则目录和分支都在,之后可回来继续;删除则连工作一起删。
  • -p 非交互跑的:没有退出询问,不会清理,自己用 git worktree remove 删。

本站观点「合并」没有专门命令,因为不需要:工作都在 worktree-<name> 分支上,且历史共享,回主 checkout 直接 git merge worktree-<name>,或推分支走 PR,和平时合并任何分支一样。

官方subagent 也能各领一个 worktree:对 Claude 说「use worktrees for your agents」,或在自定义 subagent 的 frontmatter 里写 isolation: worktree 固定下来(承接 D10)。subagent 的临时 worktree 用完没改动就自动删;有改动的留在盘上,由一个周期清扫按 cleanupPeriodDays 设置回收——清扫会跳过仍有工作的,也永远不碰你用 --worktree 亲手开的。

agent view:所有后台会话,一屏总览

官方agent view 用 claude agents 打开,是所有后台会话的一块屏幕:什么在跑、什么在等你输入、什么已完成。每一行是一个完整的 Claude Code 会话,由一个独立的 supervisor 进程托管,不需要终端挂着也持续运行。会话按状态分组,「Ready for review」(已开 PR)和「Needs input」排最上面;行首图标的颜色与动画表示状态:动画=在干活,黄=等你输入,绿=完成,红=失败。行内的一句话摘要由 Haiku 级模型生成,会话开了 PR 时行尾还会出现按状态着色的 #1234 标签。注意它目前是 research preview,需要 Claude Code v2.1.139 以上,界面和快捷键可能变化。

官方核心操作一圈:在底部输入框敲一句任务按 Enter 就派发一个新后台会话(每敲一句都是新会话,可以连发几个并行);选中某行按 Space 打开 peek 面板看它最近的输出或正在问的问题,直接打字回复;按 Enter 或 → attach 进入完整对话,空输入框按 ← detach 回列表;Esc 退出 agent view,会话照常在跑。已有的前台会话用 /bg(或空输入框按 ←)丢进后台;shell 里 claude --bg "任务" 直接派发,配 claude attach / logs / stop / rm <id> 从命令行管理。两个限制:每个后台会话都独立消耗订阅额度,并行十个就十倍速烧;会话跑在本机,休眠可存活,关机即停。

两者怎么扣在一起

官方agent view 的文件隔离正是靠 worktree:每个后台会话从你的工作目录启动,但动手改文件之前会自动移进 .claude/worktrees/ 下自己的 worktree——并行会话读同一份 checkout,写各写各的。已经身在某个 worktree 里、或目录根本不是 git 仓库(且没配 WorktreeCreate hook)时跳过;想彻底关掉,把项目设置里的 worktree.bgIsolation 设为 "none"。后台会话在 worktree 里改完代码,收尾时会主动保全工作:不问自 commit,仓库有远程就推分支,任务需要时开 draft PR;但绝不 push 到 main/master、不 force-push、不 merge,而且 CLAUDE.md 或任务里你自己的 git 约定优先。在 agent view 里按两次 Ctrl+X 删除会话会连它的 worktree 一起删(未提交的改动也没了),不过有未推送 commit 的 worktree 永远不会被删。

派发任务 agent view 输入框 或 claude --bg 后台会话 supervisor 托管 不占终端也在跑 改文件前先隔离 自动移入自己的 .claude/worktrees/ 完工保全工作 commit + push 分支 需要时开 draft PR 行状态:Working → Needs input(等你答)→ Completed / Failed 任意时刻:Space 预览 · Enter 进入 · ← 回列表;删除行会连 worktree 一起删
后台会话的一生:派发后由 supervisor 托管,改文件前先进 worktree,收尾时 commit / push / draft PR 保全工作。

当天能做完的实操

需要一个 git 仓库项目。全程约 25 分钟。

  1. 跑 claude --version 确认版本(agent view 需要 v2.1.139+;本站写作时最新为 2.1.222)。如果这个项目还没跑过 Claude,先在项目根跑一次 claude 接受 workspace trust,否则 --worktree 会报错退出。
  2. 把 .claude/worktrees/ 加进项目 .gitignore。预期:后面开的 worktree 不会污染主 checkout 的 git status。
  3. 跑 claude --worktree demo。预期:会话在 .claude/worktrees/demo/ 里启动,分支是 worktree-demo。
  4. 把下面的 prompt 原样粘贴给它,让它自证隔离:
你现在应该在一个 git worktree 里。请依次:
1. 运行 pwd 和 git branch --show-current,告诉我当前目录和分支;
2. 在 README.md 末尾加一行「worktree 隔离测试」,commit 到当前分支,不要 push;
3. 运行 git worktree list,用一句话解释输出里主 checkout 和当前 worktree 的关系。
  1. 另开一个终端,在主 checkout 跑 git status 和 git worktree list。预期:主 checkout 干净、README 没变,但 git worktree list 列出两行——隔离与共享同时得到验证。
  2. 退出 worktree 会话。预期:因为里面有新 commit,Claude 询问保留还是删除;选保留。然后在主 checkout 合并并清理:git merge worktree-demo,再 git worktree remove .claude/worktrees/demo。
  3. 体验 agent view:跑 claude agents,在底部输入框敲一个小任务(如「总结这个仓库的目录结构」)按 Enter。预期:出现一行,图标动画表示 Working;按 Space peek 它的进展,按 Enter attach 进完整对话,空输入框按 ← 回列表。完成后按两次 Ctrl+X 删掉这行(记住:它的 worktree 会一起删)。

验收标准

  • 能不看笔记说清 worktree 和 clone 的区别:哪些是隔离的(文件、分支、目录),哪些是共享的(.git 历史、远程、plugins、权限批准)。
  • 实操跑通:--worktree 会话里 commit 后,主 checkout 立即能 merge 该分支;退出时见到了清理询问。
  • 能说出后台会话什么时候自动进 worktree、什么时候跳过,以及 agent view 里删除会话对 worktree 意味着什么。
  • 自测题:你用 claude -p --worktree ci-run 跑了个一次性任务,结束后这个 worktree 还在吗?怎么清掉?(答案:在——非交互运行没有退出清理,需自己 git worktree remove。)
下一步D12 讲 agent teams 与 dynamic workflows:会话之间不只各干各的,还要互相发消息、协同分工——文件隔离(本课)加上任务编排(D10、D12),才是完整的并行拼图。