Claude Code worktree 用法：用 claude --worktree 并行跑多个会话

内容依据 2026 年 11 月的 Claude Code worktree 官方文档。Claude Code 更新很快，参数行为如有不同，以文档为准。

为什么要在 worktree 里跑 Claude Code？

两个 Claude Code 会话放在同一个目录，会改同一批文件：一个会话的重构出现在另一个的 diff 里，测试失败的原因两边都说不清，git 也在同一个暂存区上操作。git worktree 让每个会话有自己的文件和分支，同时共用一个仓库，一个会话提交的 commit，另一个不用复制就能看到。

在 worktree 里启动会话

claude --worktree feature-auth
# 在另一个终端里
claude --worktree fix-login

• worktree 位于仓库根目录下的 .claude/worktrees/<名字>/。
• 分支名是 worktree-<名字>。不写名字时，Claude 会自动生成一个，比如 bright-running-fox。
• 默认从远端的默认分支（通常是 origin/main）创建，而不是从你当前检出的分支。
• 把 .claude/worktrees/ 加进 .gitignore，这些目录就不会在主目录里显示成未跟踪文件。

也可以在会话中途让 Claude “在 worktree 里工作”，它会新建一个 worktree 并把会话移过去。

从 PR 或当前分支开始

claude --worktree "#1234"

这会拉取 PR #1234，并创建 .claude/worktrees/pr-1234。参数要加引号，否则 shell 会把 # 当成注释。如果想从本地当前的 HEAD 而不是远端默认分支创建，在 Claude Code 设置里加上 "worktree": { "baseRef": "head" }。

复制 .env 等被 ignore 的文件

新 worktree 里只有被跟踪的文件，.env、.env.local 这类被 ignore 的配置都不在。在仓库根目录创建 .worktreeinclude，按 .gitignore 的语法写：

.env
.env.local
config/secrets.json

只有匹配规则并且被 git ignore 的文件才会被复制。依赖不会复制，需要在每个 worktree 里安装，或者让 Claude 第一步先装好。

退出时会发生什么

• 没有改动：未命名的会话，Claude 会自动删除 worktree 和分支；命名过的会话会先问你。
• 有改动或新 commit：Claude 会问你保留还是删除。保留的话，之后用它打印出的 claude --worktree <名字> --resume 继续。
• 非交互运行（claude -p --worktree …）没有退出提示，worktree 会留下来并处于锁定状态。要删除，先 git worktree unlock <路径>，再 git worktree remove <路径>。

选择“删除”会连同目录、分支和里面所有的工作一起删掉。不确定 commit 有没有 push 或合并时，先查清楚再回答。怎么查见 worktree 清理清单。

让子 agent 也用独立 worktree

子 agent 也可以在临时 worktree 里运行。直接让 Claude “给你的 agent 用 worktree”，或者在自定义子 agent 的 frontmatter 里加上 isolation: worktree，让它固定这样运行：

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

子 agent 没有改动时，它的 worktree 会被自动删除；还留着工作的 worktree 会保留，直到定期清理能安全地删掉它。

常见的坑

• 先确认信任。在从没运行过 Claude 的目录里，先单独运行一次 claude 接受信任提示，否则 --worktree 会报错退出。
• 隔离是强制的。会话在 worktree 里时，Claude Code 会拦截对主目录文件的修改，以及被重定向到主目录的 git 命令。
• 权限批准是共享的。在 worktree 里选“不再询问”，规则会保存到主目录的设置里，对这个仓库的所有 worktree 都生效。
• 分支越积越多。每个保留的会话都会留下一个 worktree-* 分支。并行跑一周后，很容易攒下一堆：有的已经合并，有的还没有。

一次看清所有 Claude Code worktree

会话一多，难的不再是创建 worktree，而是弄清每个在干什么。Orchard 会列出你 Mac 上所有项目的所有 worktree，包括 .claude/worktrees/ 下的那些。它标出 Claude Code 此刻在哪个目录工作，提示哪个会话好一阵没改文件、可能在等你，并告诉你哪些 worktree-* 分支已经进了 main、可以安全清理，每个结论都附依据。

常见问题