用 worktree 并行运行会话

git worktree 是一个独立的工作目录，有自己的文件和分支，同时与主检出共享仓库历史和远程。让每个 Claude Code 会话在自己的 worktree 里运行，意味着一个会话里的编辑不会碰到另一个会话里的文件，所以并行会话之间不会冲突。

worktree 需要 git 仓库；其他版本控制系统要配置 Hook 来替换 git 逻辑。在桌面应用里，启动会话时选 worktree 选项就能给它自己的 worktree。worktree 只隔离文件编辑；子智能体在单个会话内拆分工作，跨会话消息让 Claude 在你各 worktree 的会话之间传递发现。

大多数会话只需要前两节：在 worktree 里启动 Claude，退出时清理。

在 worktree 里启动 Claude

传 --worktree 或 -w 加一个名字，创建隔离的 worktree 并在其中启动 Claude。默认 worktree 创建在仓库根目录的 .claude/worktrees/<name>/ 下，分支名为 worktree-<name>：

claude --worktree feature-auth

在另一个终端里用不同名字再运行同样的命令，就启动了第二个隔离的会话。省略名字时，Claude 会生成一个，如 bright-running-fox。

交互运行需要工作区信任：如果你之前没在该目录运行过 Claude，先在那里运行一次 claude 接受信任对话框，否则 --worktree 会报错退出。用 -p 的非交互运行跳过信任检查。建议把 .claude/worktrees/ 加进 .gitignore，让 worktree 的内容不作为未跟踪文件出现在主检出里。

设置 worktree 环境：worktree 是全新的检出，所以要在里面初始化开发环境：让 Claude 安装依赖，或自己在 .claude/worktrees/ 下的 worktree 目录里运行项目的设置。想把 .env 这类被 gitignore 的文件自动带进每个新 worktree，添加 .worktreeinclude 文件。

让 Claude 创建 worktree：会话中也可以请 Claude「work in a worktree」，它用 EnterWorktree 工具创建。进入 worktree 后，Claude 可以对目标路径调用 EnterWorktree 直接切到 .claude/worktrees/ 下的另一个。当 Claude 进入仓库 .claude/worktrees/ 目录之外的路径时，Claude Code 会先请求你批准，因为这次移动会把会话的工作目录、写权限以及 CLAUDE.md 和设置这类项目配置带到那个位置。

Hook 路径不跟随 worktree：Claude 进入 worktree 后，Claude Code 保持 Hook 里的 ${CLAUDE_PROJECT_DIR} 不变（仍指向会话启动时的项目根，所以 ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh 仍在主检出里运行脚本），而用另一种方式把 worktree 路径传给它们：Hook 输入 JSON 里的 cwd 字段是 worktree 根，Claude 运行 cd 时它也会再次移动。Hook 需要 worktree 路径时读它。

清理 worktree

退出交互式 worktree 会话时，Claude 会检查 worktree 里有没有删除会丢掉的工作：已改动或未跟踪的文件、已检出子模块里未提交的工作，以及新提交。

• worktree 是干净的：对没命名的会话，Claude 自动删除 worktree 及其分支；命名的会话会先提示你，让你可以保留 worktree 以后用
• worktree 里有工作：Claude 提示你保留还是删除。保留会保存目录和分支，想以后回来，运行退出时 Claude Code 打印的 claude --worktree <name> --resume 命令；删除会删掉 worktree 目录及其分支，连同未提交的改动
• worktree 的状态无法验证：当 Claude Code 无法统计改动或无法检查其子模块检出时，它会提示你，而不是自动删除，提示里会点明它没能检查什么

用 -p 的非交互运行没有退出提示，所以 Claude 不会清理它们的 worktree。想删一个，运行 git worktree remove（有未提交改动或未跟踪文件时加 --force）。

恢复 worktree 会话

恢复一个没有「退出」就结束在 worktree 里的会话时，Claude Code 会把会话带回那个 worktree。交互恢复、非交互模式下的 --continue 和 --resume，以及 Agent SDK 都是如此。带回之前，Claude Code 会验证该 worktree 仍是与主检出分离的检出，不通过则拒绝重新进入。启动位置和恢复方式会改变它重新进入什么：--fork-session 创建的分叉会话从你启动 Claude 的目录开始，原会话的 worktree 保持不动；如果 worktree 目录已不存在，Claude Code 在你启动 Claude 的目录里恢复会话，告诉你 worktree 没了，并清除会话的 worktree 绑定。

Claude Code 如何强制隔离

会话被隔离在 worktree 里时，Claude Code 会阻止下面四项检查所定义的工具调用。无论你是用 --worktree 启动、Claude 用 EnterWorktree 进入，还是恢复了 worktree 会话，规则都一样；同样的强制也覆盖隔离会话派生的每个子智能体。

• 文件编辑：阻止针对主检出里路径的 Edit、Write 或 NotebookEdit
• 命令工作目录：阻止工作目录解析到主检出、或无法验证其工作目录留在主检出之外的 Bash、PowerShell 或 Monitor 命令
• git 重定向：阻止把 git 重定向到主检出的 Bash 或 Monitor 命令，重定向可以通过 git -C、--git-dir、GIT_DIR 或 GIT_WORK_TREE 变量，或运行 git 之前 cd 到主检出来实现
• 命令形态：当无法从命令文本验证命令运行的任何 git 都留在 worktree 内时（例如命令名在运行时才计算、语法无法解析），阻止 Bash 或 Monitor 命令

Claude 把每次拒绝看作一个点明 worktree 并说明如何继续的工具错误。

用 worktree 隔离子智能体

子智能体可以在自己的 worktree 里运行，让并行编辑不冲突。请 Claude「use worktrees for your agents」，或者给自定义子智能体的前置信息加 isolation: worktree 让隔离永久生效。下面这个 .claude/agents/ 里的子智能体总是在自己的 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 Code 自动删除；有改动的 worktree 会留在磁盘上，直到周期性清理能在不丢工作的前提下删除它。子智能体的 worktree 与 --worktree 使用同样的基础分支。

清理子智能体和后台会话的 worktree：Claude Code 运行周期性清理，删除为子智能体和后台会话创建的、比你的 cleanupPeriodDays 设置更老的 worktree。以下情况清理会保留 worktree：它仍有工作（改动或未跟踪的文件，或未推送的提交）；你自己用 git worktree add 创建的；属于一个你没有转入后台的 --worktree 会话的。想清理清理机制保留的 worktree，运行 git worktree remove；如果 git 因 worktree 被锁而拒绝，先对它运行 git worktree unlock。

自定义 worktree 创建

Claude Code 创建 worktree 的默认设置覆盖大多数会话：创建在 .claude/worktrees/ 下，从仓库的默认分支分出，只检出被跟踪的文件。

选择基础分支：新 worktree 从仓库默认分支分出。想从你当前的工作分出，在设置里设 worktree.baseRef，它接受两个值："fresh"（默认）从远程的仓库默认分支分出（通常是 main），所以 worktree 以与远程匹配的干净树开始；"head" 从你当前本地的 HEAD 分出，所以 worktree 带有你未推送的提交和功能分支状态，适合隔离需要在进行中的工作上操作的子智能体。

官方原文还涵盖 .worktreeinclude 的写法、稀疏检出、git LFS 内容缺失的处理，以及用 WorktreeCreate/WorktreeRemove Hook 支持非 git 版本控制。