Git Worktree 生命周期钩子：WorktreeCreate 与 Remove

为了支持高效的并行开发流，Claude Code 内建了对 Git Worktree 的深度集成。WorktreeCreate 和 WorktreeRemove 这一组钩子允许开发者在创建或销毁物理工作树时，自动完成环境配置或资源清理。

先搞清楚这是什么

这组钩子本质上是 物理隔离开发流的自动化生命周期管理（Isolated Workflow Management）。

它们不是一个通用的 Git 事件监听器。它们专门为解决“新环境冷启动”和“旧环境清理”而生。每当通过 Claude 的指令（如在开启并行任务或子代理时）创建一个新的 Git Worktree，系统会提供一个入口，让你能同步地在新目录里执行 npm install、链接 node_modules 或注入特定的本地开发配置。

源码级拆解

这组钩子的触发与 Git 状态及 worktree 指令深度绑定，逻辑实现在 claude-code-opensource/src/utils/worktree.ts 中：

1. 创建流程（WorktreeCreate）：当系统决定开启一个新的 Worktree 会话时，在物理执行 git worktree add 之后，系统会立即派发 WorktreeCreate 事件。
   • 上下文注入：输入参数包含了 worktree_path（新工作树的绝对路径）和 branch（关联的分支名）。
   • 并行预热：开发者利用此钩子在新工作树中执行必要的构建任务，确保模型进入该会话时环境已经就绪。
2. 销毁流程（WorktreeRemove）：当一个 Worktree 会话结束并被系统回收时，触发 WorktreeRemove 事件。
   • 收口清理：用于删除该工作树产生的临时文件、注销相关的本地数据库记录、或断开特定环境的连接。
3. 状态隔离与 CWD 设置：由于每个 Worktree 都拥有独立的磁盘路径，这组钩子在运行时会显式将 CWD 设置为目标 Worktree 的根路径，确保钩子内的 Shell 命令运行在正确的物理上下文中。

实战注意事项

• 物理操作后触发：这些钩子运行在物理文件系统操作（Add/Remove）之后。这意味着当 WorktreeCreate 运行时，目录已经存在并可读写。
• 非强制性触发：它们仅由 Claude Code 内建的 Worktree 管理逻辑驱动（例如在 run_parallel 或相关的 Subagent 任务中）。如果你手动在终端运行外部的 git worktree 命令，Claude 的 Hook 系统不会捕获这些外部事件。
• 执行权重风险：WorktreeCreate 往往涉及较重的操作（如 npm install），建议将其设计为非阻塞或提供进度反馈，避免给用户造成“程序挂起”的假象。
• 清理失败处理：WorktreeRemove 的执行失败仅会在调试模式下记录日志，通常不会阻止物理目录的删除逻辑。

接下来看什么

• 如果你想了解 Claude 如何在多个 Worktree 之间切换，请看 Git Worktree 协作：隔离的并行开发流。
• 如果你想了解 Hook 的基础调度机制，请看 Hook 系统架构解析。
• 如果你关心并行任务的 Token 消耗，请看 会话恢复与选择器：从本地索引到运行时重载。

源码锚点

• claude-code-opensource/src/utils/worktree.ts — Worktree 管理的核心实现。

📄 src/utils/worktree.ts — Worktree 管理的核心实现。L23-27 of 1520

  readWorktreeHeadSha,
  resolveGitDir,
  resolveRef,
} from './git/gitFilesystem.js'
import {

• claude-code-opensource/src/types/hooks.ts — WorktreeCreateHookInput 结构定义。

📄 src/types/hooks.ts — `WorktreeCreateHookInput` 结构定义。L22-24 of 291

export function isHookEvent(value: string): value is HookEvent {
  return HOOK_EVENTS.includes(value as HookEvent)
}