用途:让每个智能体或任务在独立分支上工作,互不干扰主工作目录,适用于并行、长时间或涉及多文件的开发任务。
主要能力:
- Git worktree 管理命令:git worktree add .claude/worktrees/<name> -b <branch>、git worktree list、git worktree remove、git worktree prune。
- Claude Code 工具:EnterWorktree 切换工作上下文到隔离 worktree,分支不存在时从当前 HEAD 创建;ExitWorktree 返回主目录,需成对使用。
- Agent 工具 isolation: "worktree" 可自动创建、运行子智能体,无改动时清理,否则返回路径和分支名供审查合并。
- 分支—worktree 一一对应,目录按分支 slug 命名,便于 list 与 remove。
- 多智能体扇出:编排器在单次调用中并行启动多个智能体,各自分支,完成后合并或提 PR。
生命周期:创建→在 worktree 内编辑→提交(归属分支)→ExitWorktree→合并/PR→git worktree remove + git branch -d。删除前应确认分支已合并、无未暂存改动、无进程占用、创建者已退出。
限制与注意:
- 同一分支不能在两个 worktree 同时检出,git 会报 fatal。
- 应避免并行分支修改同一文件,以减少合并冲突。
- 不应长期保留闲置 worktree,会占用磁盘并干扰 prune。
- 所有 worktree 共享同一 .git 目录。
- 使用 Agent SDK 时可用 forkSession 分支会话历史(Python/TypeScript),会话存于 ~/.claude/projects/<url-encoded-cwd>/<session-id>.jsonl,可用 resume 恢复。
适用场景:超过 10 分钟的任务、涉及多文件、并行独立任务更适合 worktree;单文件快速修复、只读研究或需与父上下文共享的任务用主上下文。CLI 编排默认用 worktree,SDK 程序化开发用 forkSession。