clawt 3.7.1 → 3.8.0

package/docs/post-create-hook.md

@@ -0,0 +1,142 @@
+### postCreate Hook 机制
+
+#### 概述
+
+postCreate hook 是在 worktree 创建完成后自动执行的钩子命令，可用于执行任意初始化操作（如安装依赖、生成配置文件、编译资源等）。`create` 和 `run` 命令在创建 worktree 之后，会尝试解析并执行 postCreate hook。
+
+hook 以 **fire-and-forget** 模式后台异步并行执行，不阻塞主流程（不 await）。执行结果仅写入日志，不影响后续 Claude Code 的启动或系统提示。
+
+#### 配置方式
+
+支持两种配置方式，按优先级从高到低：
+
+| 优先级 | 配置方式 | 来源标识 | 说明 |
+| --- | --- | --- | --- |
+| 1 | 项目配置 `postCreate` 字段 | `projectConfig` | 通过 `clawt init show` 交互式设置，或直接编辑 `~/.clawt/projects/<projectName>/config.json` |
+| 2 | 项目仓库 `.clawt/postCreate.sh` 脚本 | `postCreateScript` | 在项目根目录下创建 `.clawt/postCreate.sh` 脚本文件 |
+
+**配置方式 1 — 项目配置：**
+
+```bash
+# 通过 init show 交互式设置
+clawt init show
+# 选择 postCreate 配置项，输入命令（如 npm install）
+
+# 或直接编辑配置文件
+# ~/.clawt/projects/<projectName>/config.json
+{
+  "clawtMainWorkBranch": "main",
+  "postCreate": "npm install"
+}
+```
+
+**配置方式 2 — postCreate.sh 脚本：**
+
+```bash
+# 在项目根目录创建脚本
+mkdir -p .clawt
+cat > .clawt/postCreate.sh << 'EOF'
+#!/bin/bash
+npm install
+EOF
+chmod +x .clawt/postCreate.sh
+```
+
+> **自动权限修复**：如果检测到 `.clawt/postCreate.sh` 文件存在但不可执行，会自动尝试 `chmod +x` 添加执行权限。自动 chmod 失败时会打印警告，提示用户手动添加权限。
+
+#### 命令行选项
+
+`create` 和 `run` 命令均支持 `--post-create` / `--no-post-create` 选项：
+
+```bash
+# 默认行为：自动执行 postCreate hook（如果已配置）
+clawt create -b feat
+clawt run -b feat
+
+# 跳过 postCreate hook
+clawt create -b feat --no-post-create
+clawt run -b feat --no-post-create
+```
+
+| 选项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--post-create` | `true` | 执行 postCreate hook（默认开启） |
+| `--no-post-create` | — | 跳过 postCreate hook |
+
+#### 执行流程
+
+```
+创建 worktree 完成
+       ↓
+  --no-post-create？ ── 是 ──→ 跳过，打印提示，直接返回
+       ↓ 否
+  解析 hook 配置
+       ↓
+  有配置？ ── 否 ──→ 打印"未配置"，直接返回
+       ↓ 是
+  打印 hook 来源 + 后台执行提示
+       ↓
+  fire-and-forget：异步并行启动所有 worktree 的 hook
+  （spawn + shell: true + stdio: 'ignore'，不阻塞主流程）
+       ↓
+  主流程继续执行（输出日志、启动 Claude Code 等）
+       ↓
+  后台 hook 完成后写入日志汇总（成功数 + 失败数）
+```
+
+#### 解析优先级（resolvePostCreateHook）
+
+解析函数 `resolvePostCreateHook()`（位于 `src/hooks/post-create.ts`）按以下优先级查找 hook 配置：
+
+1. **项目配置**：读取 `loadProjectConfig()` 的 `postCreate` 字段，非空则使用
+2. **postCreate.sh 脚本**：检查主 worktree 路径下的 `.clawt/postCreate.sh` 是否存在
+
+两者都不存在时返回 `null`，表示无 hook 配置。
+
+#### 执行细节
+
+- **执行方式**：通过 `spawn(hook.command, { cwd: worktree.path, stdio: 'ignore', shell: true })` 在每个 worktree 目录下异步并行执行（`Promise.all`）
+- **失败处理**：单个 worktree 的 hook 执行失败（非零退出码或异常）仅写入日志，不阻塞其他 worktree 和后续流程
+- **结果汇总**：后台执行完毕后通过 `.then()` 回调写入日志汇总（成功数 + 失败数）
+- **返回值**：`runPostCreateHooks()` 返回 `void`——以 fire-and-forget 模式后台执行，不等待结果
+
+#### 系统提示
+
+Claude Code 启动时统一使用 `APPEND_SYSTEM_PROMPT` 常量（定义在 `src/constants/config.ts`）作为 `--append-system-prompt` 参数值，内容为通用的 worktree 目录提示，不因 hook 执行结果而变化。
+
+#### 相关类型定义
+
+类型定义位于 `src/types/postCreateHook.ts`：
+
+| 类型 | 说明 |
+| --- | --- |
+| `PostCreateHookSource` | hook 来源枚举类型：`'projectConfig'` \| `'postCreateScript'` |
+| `PostCreateHookResult` | 单个 worktree 的 hook 执行结果，包含 `worktreePath`、`branch`、`success`、`source`、`error?` |
+| `ResolvedHook` | hook 解析结果，包含 `command`（待执行命令）和 `source`（来源） |
+
+#### 提示消息
+
+消息常量定义在 `src/constants/messages/post-create.ts`：
+
+| 消息 | 说明 |
+| --- | --- |
+| `HOOK_SKIPPED` | `--no-post-create` 跳过时的提示 |
+| `HOOK_NOT_CONFIGURED` | 未配置 hook 时的提示 |
+| `HOOK_SOURCE_INFO(source)` | hook 来源信息 |
+| `HOOK_EXECUTING(branch, command)` | hook 开始执行提示 |
+| `HOOK_SUCCESS(branch)` | hook 执行成功提示 |
+| `HOOK_FAILED(branch, error)` | hook 执行失败警告 |
+| `HOOK_SUMMARY(succeeded, failed)` | hook 执行汇总 |
+| `HOOK_BACKGROUND_START(count, command)` | hook 后台执行中提示（worktree 数量和命令） |
+| `POST_CREATE_SCRIPT_AUTO_CHMOD(path)` | postCreate.sh 自动添加执行权限提示 |
+| `POST_CREATE_SCRIPT_NOT_EXECUTABLE(path)` | postCreate.sh 不可执行且自动 chmod 失败时的降级提示 |
+
+#### 实现要点
+
+- hook 解析和执行逻辑位于 `src/hooks/post-create.ts`，通过 `src/hooks/index.ts` 导出
+- 入口函数 `runPostCreateHooks` 由 `src/utils/index.ts` 统一导出
+- `create` 命令在 `createWorktrees()` 之后调用 `runPostCreateHooks(worktrees, !options.postCreate)`（fire-and-forget，不 await）
+- `run` 命令在 `createWorktrees()` / `createWorktreesByBranches()` 之后调用 `runPostCreateHooks(worktrees, !options.postCreate)`（fire-and-forget，不 await）
+- hook 内部通过 `executePostCreateHooks()` 并行启动所有 worktree 的子进程，`.then()` 回调写入日志汇总
+
+---

package/docs/project-config.md

@@ -17,7 +17,8 @@
 ```json
 {
   "clawtMainWorkBranch": "main",
-  "validateRunCommand": "npm test"
+  "validateRunCommand": "npm test",
+  "postCreate": "npm install"
 }
 ```
 
@@ -25,6 +26,7 @@
 | --- | --- | --- | --- | --- |
 | `clawtMainWorkBranch` | `string` | 是 | `""` | 项目的主工作分支名，用于 create 时检测当前分支是否为主分支，以及 sync、merge 等命令获取主分支名 |
 | `validateRunCommand` | `string` | 否 | `undefined` | validate 成功后自动执行的命令（作为 `-r` 选项的默认值）。不传 `-r` 时，validate 命令会自动从此项读取 |
+| `postCreate` | `string` | 否 | `undefined` | worktree 创建后自动执行的初始化命令（如安装依赖、生成配置文件、编译资源等）。详见 [post-create-hook.md](./post-create-hook.md) |
 
 #### 配置项定义数据源
 
@@ -42,6 +44,10 @@ export const PROJECT_CONFIG_DEFINITIONS: ProjectConfigDefinitions = {
     defaultValue: undefined as unknown as string | undefined,
     description: 'validate 成功后自动执行的命令（-r 的默认值）',
   },
+  postCreate: {
+    defaultValue: undefined as unknown as string | undefined,
+    description: 'worktree 创建后自动执行的命令，用于安装依赖等初始化操作',
+  },
 };
 
 /** 项目默认配置（从 PROJECT_CONFIG_DEFINITIONS 自动派生） */
@@ -57,7 +63,7 @@ export const PROJECT_CONFIG_DESCRIPTIONS: Record<keyof Required<ProjectConfig>,
 
 | 类型 | 说明 |
 | --- | --- |
-| `ProjectConfig` | 项目级配置接口，包含 `clawtMainWorkBranch`（必填）和 `validateRunCommand`（可选） |
+| `ProjectConfig` | 项目级配置接口，包含 `clawtMainWorkBranch`（必填）、`validateRunCommand`（可选）和 `postCreate`（可选） |
 | `ProjectConfigItemDefinition<T>` | 单个配置项定义，含 `defaultValue`（默认值）、`description`（描述）、可选 `allowedValues`（枚举值列表，仅对 string 类型有效） |
 | `ProjectConfigDefinitions` | 所有配置项的完整定义映射，键为 `ProjectConfig` 的所有属性名，值为对应的 `ProjectConfigItemDefinition` |
 
@@ -67,6 +73,7 @@ export const PROJECT_CONFIG_DESCRIPTIONS: Record<keyof Required<ProjectConfig>,
 export interface ProjectConfig {
   clawtMainWorkBranch: string;
   validateRunCommand?: string;
+  postCreate?: string;
 }
 
 export interface ProjectConfigItemDefinition<T> {

package/docs/run.md

@@ -24,6 +24,7 @@ clawt run -b <branchName>
 | `-f`      | 否   | 从任务文件读取任务列表（与 `--tasks` 互斥）                    |
 | `-c`      | 否   | 最大并发数，`0` 表示不限制                                    |
 | `--dry-run` | 否 | 试运行模式，仅输出预览信息不实际执行                            |
+| `--post-create` | 否 | 执行 postCreate hook（默认开启，`--no-post-create` 跳过）。详见 [post-create-hook.md](./post-create-hook.md) |
 
 **互斥约束：**
 
@@ -73,21 +74,24 @@ clawt run -b <branchName>
 1. 调用 `loadTaskFile(options.file)` 读取解析文件
 2. **有 `-b` 参数**：忽略文件中的分支名，用 `-b` 值自动编号创建 worktree（`createWorktrees(branch, count)`）
 3. **无 `-b` 参数**：使用文件中每个任务的独立分支名，先 `sanitizeBranchName` 清理后调用 `createWorktreesByBranches(branches)`
-4. 调用 `executeBatchTasks(worktrees, tasks, concurrency)` 执行
+4. **执行 postCreate hook**：调用 `runPostCreateHooks(worktrees, !options.postCreate)`，以 fire-and-forget 模式后台异步并行执行，不阻塞后续流程。详见 [post-create-hook.md](./post-create-hook.md)
+5. 调用 `executeBatchTasks(worktrees, tasks, concurrency)` 执行
 
 #### --tasks 模式运行流程
 
-1. 若传了 `--tasks`，解析得到任务数组 `tasks[]`；若未传，先检测分支是否已存在（已存在则提示使用 `clawt resume -b <branchName>` 恢复会话），然后创建单个 worktree 并启动 Claude Code 交互式界面（流程结束，不进入后续并行执行阶段）
+1. 若传了 `--tasks`，解析得到任务数组 `tasks[]`；若未传，先检测分支是否已存在（已存在则提示使用 `clawt resume -b <branchName>` 恢复会话），然后创建单个 worktree，执行 postCreate hook（fire-and-forget）后启动 Claude Code 交互式界面（`launchInteractiveClaude(worktree)`），流程结束，不进入后续并行执行阶段
 2. `n = tasks.length`
 3. 按照 **5.1** 的流程创建 `n` 个 worktree
-4. 通过公共函数 `executeBatchTasks`（`src/utils/task-executor.ts`）启动批量任务执行，该函数负责进度面板渲染、SIGINT 中断处理、并发控制和汇总输出。对每个 worktree 并行启动 Claude Code CLI：
+4. **执行 postCreate hook**：调用 `runPostCreateHooks(worktrees, !options.postCreate)`，以 fire-and-forget 模式后台异步并行执行，不阻塞后续流程。详见 [post-create-hook.md](./post-create-hook.md)
+5. 通过公共函数 `executeBatchTasks`（`src/utils/task-executor.ts`）启动批量任务执行，该函数负责进度面板渲染、SIGINT 中断处理、并发控制和汇总输出。对每个 worktree 并行启动 Claude Code CLI：
    ```bash
    cd ~/.clawt/worktrees/<project>/<branchName>-<i>
-   claude -p "<tasks[i]>" --output-format stream-json --verbose --permission-mode bypassPermissions
+   claude -p "<tasks[i]>" --output-format stream-json --verbose --permission-mode bypassPermissions --append-system-prompt "<系统提示>"
    ```
+   其中 `--append-system-prompt` 使用统一的 `APPEND_SYSTEM_PROMPT` 常量（定义在 `src/constants/config.ts`）。
    使用 `stream-json` 格式可实时获取 Claude Code 的流式事件（工具调用、文本输出、最终结果），用于在进度面板中显示每个任务的实时活动描述和结果预览。流式事件解析由 `src/utils/stream-parser.ts` 负责。
-5. 进入**事件监听通知**阶段（见 [5.3](#53-任务完成通知机制)）
-6. **中断处理（Ctrl+C / SIGINT）**
+6. 进入**事件监听通知**阶段（见 [5.3](#53-任务完成通知机制)）
+7. **中断处理（Ctrl+C / SIGINT）**
    - 监听 `SIGINT` 信号，用户按下 Ctrl+C 时触发
    - 向所有正在运行的 Claude Code 子进程发送 `SIGTERM` 终止信号
    - 等待所有子进程退出后，进入清理流程：

package/docs/spec.md

@@ -37,6 +37,7 @@
   - [5.20 切换回主工作分支](./home.md)
   - [5.21 将验证分支修改覆盖回目标 Worktree](./cover-validate.md)
   - [5.22 任务文件管理](./tasks.md)
+  - [5.23 postCreate Hook 机制](./post-create-hook.md)
 - [6. 验证架构规则](#6-验证架构规则)
 - [7. 错误处理规范](#7-错误处理规范)
 - [8. 非功能性需求](#8-非功能性需求)
@@ -201,7 +202,7 @@ export const VALIDATE_BRANCH_PREFIX = 'clawt-validate-';
 
 ### 2.6 项目级配置
 
-每个 Git 项目独立的 clawt 配置，存放在 `~/.clawt/projects/<projectName>/config.json`。包含项目的主工作分支名（`clawtMainWorkBranch`）、validate 自动运行命令（`validateRunCommand`）等配置项。通过 `clawt init` 命令设置，核心命令执行前会校验该配置是否存在。
+每个 Git 项目独立的 clawt 配置，存放在 `~/.clawt/projects/<projectName>/config.json`。包含项目的主工作分支名（`clawtMainWorkBranch`）、validate 自动运行命令（`validateRunCommand`）、worktree 创建后自动执行的初始化命令（`postCreate`）等配置项。通过 `clawt init` 命令设置，核心命令执行前会校验该配置是否存在。
 
 详细的配置项列表、类型定义、工具函数和设置方式见 [项目级配置文档](./project-config.md)。
 
@@ -344,6 +345,7 @@ async function interactiveConfigEditor<T extends object>(
 - [5.20 切换回主工作分支](./home.md)
 - [5.21 将验证分支修改覆盖回目标 Worktree](./cover-validate.md)
 - [5.22 任务文件管理](./tasks.md)
+- [5.23 postCreate Hook 机制](./post-create-hook.md)
 
 ---
 
@@ -394,6 +396,7 @@ async function interactiveConfigEditor<T extends object>(
 - Worktree 创建为串行执行（Git worktree 不支持并行写入）
 - Claude Code 任务为并行执行（各自独立进程）
 - 任务完成检测：监听子进程 `close` 事件，事件驱动
+- 命令执行缓冲区：所有 `execSync` / `execFileSync` 调用统一使用 `EXEC_MAX_BUFFER`（200MB，定义在 `src/constants/git.ts`），避免大分支 diff 输出超过 Node.js 默认 1MB 限制触发 `ENOBUFS` 错误
 
 ### 8.2 兼容性
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/create.ts

@@ -11,6 +11,7 @@ import {
   printSuccess,
   printInfo,
   printSeparator,
+  runPostCreateHooks,
 } from '../utils/index.js';
 
 /**
@@ -23,6 +24,7 @@ export function registerCreateCommand(program: Command): void {
     .description('批量创建 worktree 及对应分支（含验证分支）')
     .requiredOption('-b, --branch <branchName>', '分支名')
     .option('-n, --number <count>', '创建数量', '1')
+    .option('--post-create', '执行 postCreate hook（默认开启，--no-post-create 跳过）', true)
     .action(async (options: CreateOptions) => {
       await handleCreate(options);
     });
@@ -49,6 +51,9 @@ async function handleCreate(options: CreateOptions): Promise<void> {
 
   const worktrees = createWorktrees(options.branch, count);
 
+  // 执行 postCreate hook
+  runPostCreateHooks(worktrees, !options.postCreate);
+
   printSuccess(MESSAGES.WORKTREE_CREATED(worktrees.length));
   printInfo('');
 

package/src/commands/run.ts

@@ -20,6 +20,7 @@ import {
   parseTasksFromOptions,
   executeBatchTasks,
   printDryRunPreview,
+  runPostCreateHooks,
 } from '../utils/index.js';
 
 /**
@@ -35,6 +36,7 @@ export function registerRunCommand(program: Command): void {
     .option('-c, --concurrency <n>', '最大并发数，0 表示不限制')
     .option('-f, --file <path>', '从任务文件读取任务列表（与 --tasks 互斥）')
     .option('--dry-run', '预览模式，仅展示任务计划不实际执行')
+    .option('--post-create', '执行 postCreate hook（默认开启，--no-post-create 跳过）', true)
     .action(async (options: RunOptions) => {
       await handleRun(options);
     });
@@ -86,6 +88,9 @@ async function handleRunFromFile(options: RunOptions): Promise<void> {
     worktrees = createWorktreesByBranches(branches);
   }
 
+  // 执行 postCreate hook（后台异步，不阻塞）
+  runPostCreateHooks(worktrees, !options.postCreate);
+
   // 解析并发数
   const concurrency = parseConcurrency(options.concurrency, getConfigValue('maxConcurrency'));
 
@@ -176,6 +181,10 @@ async function handleRun(options: RunOptions): Promise<void> {
 
     const worktrees = createWorktrees(options.branch, 1);
     const worktree = worktrees[0];
+
+    // 执行 postCreate hook（后台异步，不阻塞）
+    runPostCreateHooks(worktrees, !options.postCreate);
+
     printSuccess(MESSAGES.WORKTREE_CREATED(1));
 
     launchInteractiveClaude(worktree);
@@ -193,5 +202,8 @@ async function handleRun(options: RunOptions): Promise<void> {
   // 创建 worktree
   const worktrees = createWorktrees(options.branch, count);
 
+  // 执行 postCreate hook（后台异步，不阻塞）
+  runPostCreateHooks(worktrees, !options.postCreate);
+
   await executeBatchTasks(worktrees, tasks, concurrency);
 }

package/src/constants/config.ts

@@ -3,7 +3,7 @@ import { VALID_TERMINAL_APPS } from './terminal.js';
 
 /** Claude Code 系统约束提示 */
 export const APPEND_SYSTEM_PROMPT =
-  'Currently, you are in the git worktree directory. There are no dependencies. To save disk space and improve the speed of task completion, installing dependencies is prohibited.';
+  'Currently, you are in the git worktree directory.';
 
 /**
  * 配置项完整定义（单一数据源）

package/src/constants/messages/index.ts

@@ -17,6 +17,7 @@ import { INIT_MESSAGES } from './init.js';
 import { COVER_VALIDATE_MESSAGES } from './cover-validate.js';
 import { HOME_MESSAGES } from './home.js';
 import { TASKS_CMD_MESSAGES } from './tasks.js';
+import { POST_CREATE_MESSAGES } from './post-create.js';
 import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE, PANEL_CONFIGURED_BRANCH, PANEL_CONFIGURED_BRANCH_DELETED, PANEL_CONFIGURED_BRANCH_MISMATCH, PANEL_NOT_INITIALIZED, PANEL_UNKNOWN_DATE, PANEL_SYNCED_WITH_MAIN, PANEL_COMMITS_AHEAD, PANEL_COMMITS_BEHIND } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
@@ -46,4 +47,5 @@ export const MESSAGES = {
   ...COVER_VALIDATE_MESSAGES,
   ...HOME_MESSAGES,
   ...TASKS_CMD_MESSAGES,
+  ...POST_CREATE_MESSAGES,
 } as const;

package/src/constants/messages/post-create.ts

@@ -0,0 +1,29 @@
+/** postCreate hook 相关提示消息 */
+export const POST_CREATE_MESSAGES = {
+  /** hook 执行跳过（--no-post-create） */
+  HOOK_SKIPPED: '已跳过 postCreate hook（--no-post-create）',
+  /** 无 hook 配置 */
+  HOOK_NOT_CONFIGURED: '未配置 postCreate hook，跳过',
+  /** hook 来源提示 */
+  HOOK_SOURCE_INFO: (source: string) => `postCreate hook 来源: ${source}`,
+  /** hook 开始执行 */
+  HOOK_EXECUTING: (branch: string, command: string) =>
+    `[${branch}] 正在执行 postCreate hook: ${command}`,
+  /** hook 执行成功 */
+  HOOK_SUCCESS: (branch: string) => `[${branch}] postCreate hook 执行成功`,
+  /** hook 执行失败 */
+  HOOK_FAILED: (branch: string, error: string) =>
+    `[${branch}] postCreate hook 执行失败: ${error}`,
+  /** hook 执行汇总 */
+  HOOK_SUMMARY: (succeeded: number, failed: number) =>
+    `postCreate hook 执行完成: ${succeeded} 成功, ${failed} 失败`,
+  /** hook 后台执行中提示 */
+  HOOK_BACKGROUND_START: (count: number, command: string) =>
+    `postCreate hook 正在后台执行 (${count} 个 worktree): ${command}`,
+  /** postCreate.sh 自动添加执行权限 */
+  POST_CREATE_SCRIPT_AUTO_CHMOD: (path: string) =>
+    `${path} 不可执行，已自动添加执行权限`,
+  /** postCreate.sh 不可执行（自动 chmod 失败时降级提示） */
+  POST_CREATE_SCRIPT_NOT_EXECUTABLE: (path: string) =>
+    `检测到 ${path} 但不可执行，自动添加权限失败，请手动执行 chmod +x ${path}`,
+} as const;

package/src/constants/project-config.ts

@@ -13,6 +13,10 @@ export const PROJECT_CONFIG_DEFINITIONS: ProjectConfigDefinitions = {
     defaultValue: undefined as unknown as string | undefined,
     description: 'validate 成功后自动执行的命令（-r 的默认值）',
   },
+  postCreate: {
+    defaultValue: undefined as unknown as string | undefined,
+    description: 'worktree 创建后自动执行的命令，用于安装依赖等初始化操作',
+  },
 };
 
 /**

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { resolvePostCreateHook, executePostCreateHooks, runPostCreateHooks } from './post-create.js';

package/src/hooks/post-create.ts

@@ -0,0 +1,198 @@
+import { existsSync, accessSync, chmodSync, constants as fsConstants } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { logger } from '../logger/index.js';
+import { MESSAGES } from '../constants/index.js';
+import { loadProjectConfig } from '../utils/project-config.js';
+import { getMainWorktreePath } from '../utils/git.js';
+import { printInfo, printSuccess, printWarning } from '../utils/formatter.js';
+import type { WorktreeInfo, ResolvedHook, PostCreateHookResult } from '../types/index.js';
+
+/** 项目仓库中的 postCreate 脚本相对路径 */
+const POST_CREATE_SCRIPT_RELATIVE_PATH = '.clawt/postCreate.sh';
+
+/**
+ * 检测文件是否具有可执行权限
+ * @param {string} filePath - 文件绝对路径
+ * @returns {boolean} 是否可执行
+ */
+function isExecutable(filePath: string): boolean {
+  try {
+    accessSync(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 自动为脚本文件添加可执行权限
+ * chmod 失败时仅打印警告，不阻塞流程（后续执行阶段会自然报错）
+ * @param {string} filePath - 脚本文件绝对路径
+ */
+function autoFixExecutablePermission(filePath: string): void {
+  try {
+    chmodSync(filePath, 0o755);
+    printInfo(MESSAGES.POST_CREATE_SCRIPT_AUTO_CHMOD(filePath));
+  } catch {
+    printWarning(MESSAGES.POST_CREATE_SCRIPT_NOT_EXECUTABLE(filePath));
+  }
+}
+
+/**
+ * 将 postCreate 配置值规范化为单条命令
+ * 空字符串视为无配置
+ * @param {string | undefined} value - postCreate 配置值
+ * @returns {string | null} 规范化后的命令，无有效配置时返回 null
+ */
+function normalizeCommand(value: string | undefined): string | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+/**
+ * 按优先级解析 postCreate hook 来源和命令
+ * 优先级：项目配置 postCreate > 项目仓库 .clawt/postCreate.sh
+ * @returns {ResolvedHook | null} 解析到的 hook 配置，无配置时返回 null
+ */
+export function resolvePostCreateHook(): ResolvedHook | null {
+  // 优先级 1：项目配置中的 postCreate
+  const config = loadProjectConfig();
+  if (config?.postCreate) {
+    const command = normalizeCommand(config.postCreate);
+    if (command) {
+      return { command, source: 'projectConfig' };
+    }
+  }
+
+  // 优先级 2：项目仓库中的 .clawt/postCreate.sh
+  const mainWorktreePath = getMainWorktreePath();
+  const scriptPath = join(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
+
+  if (existsSync(scriptPath)) {
+    if (!isExecutable(scriptPath)) {
+      autoFixExecutablePermission(scriptPath);
+    }
+    return { command: scriptPath, source: 'postCreateScript' };
+  }
+
+  return null;
+}
+
+/**
+ * 获取 hook 来源的中文描述
+ * @param {ResolvedHook} hook - 解析到的 hook 配置
+ * @returns {string} 来源描述文本
+ */
+function getSourceLabel(hook: ResolvedHook): string {
+  return hook.source === 'projectConfig' ? '项目配置 (postCreate)' : '.clawt/postCreate.sh';
+}
+
+/**
+ * 异步执行单个 worktree 的 postCreate hook
+ * 通过 spawn 异步启动子进程，stdio 设为 'ignore' 静默执行
+ * @param {WorktreeInfo} worktree - worktree 信息
+ * @param {ResolvedHook} hook - 解析到的 hook 配置
+ * @returns {Promise<PostCreateHookResult>} 单个 worktree 的执行结果
+ */
+function executeOneHook(worktree: WorktreeInfo, hook: ResolvedHook): Promise<PostCreateHookResult> {
+  return new Promise((resolve) => {
+    const result: PostCreateHookResult = {
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      success: true,
+      source: hook.source,
+    };
+
+    try {
+      const child = spawn(hook.command, {
+        cwd: worktree.path,
+        stdio: 'ignore',
+        shell: true,
+      });
+
+      child.on('error', (err) => {
+        result.success = false;
+        result.error = err.message;
+        logger.error(`postCreate hook 异常: ${hook.command} @ ${worktree.path}: ${result.error}`);
+        resolve(result);
+      });
+
+      child.on('close', (code) => {
+        if (code !== null && code !== 0) {
+          result.success = false;
+          result.error = `命令退出码: ${code}`;
+          logger.error(`postCreate hook 失败: ${hook.command} (退出码: ${code}) @ ${worktree.path}`);
+        } else {
+          logger.info(`postCreate hook 成功: ${hook.command} @ ${worktree.path}`);
+        }
+        resolve(result);
+      });
+    } catch (err) {
+      result.success = false;
+      result.error = err instanceof Error ? err.message : String(err);
+      logger.error(`postCreate hook 启动失败: ${hook.command} @ ${worktree.path}: ${result.error}`);
+      resolve(result);
+    }
+  });
+}
+
+/**
+ * 对一批 worktree 异步并行执行 postCreate hook
+ * 所有 worktree 同时启动，通过 Promise.all 等待全部完成
+ * 失败仅写日志，不影响主流程
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
+ * @param {ResolvedHook} hook - 解析到的 hook 配置
+ * @returns {Promise<PostCreateHookResult[]>} 每个 worktree 的执行结果
+ */
+export function executePostCreateHooks(
+  worktrees: WorktreeInfo[],
+  hook: ResolvedHook,
+): Promise<PostCreateHookResult[]> {
+  const promises = worktrees.map((worktree) => executeOneHook(worktree, hook));
+  return Promise.all(promises);
+}
+
+/**
+ * postCreate hook 完整入口（fire-and-forget）
+ * 根据 skip 标志和配置解析结果决定是否执行 hook
+ * 异步后台执行，不阻塞主流程
+ * @param {WorktreeInfo[]} worktrees - worktree 列表
+ * @param {boolean} skip - 是否跳过 postCreate hook（--no-post-create 标志）
+ */
+export function runPostCreateHooks(
+  worktrees: WorktreeInfo[],
+  skip: boolean,
+): void {
+  // --no-post-create 直接跳过
+  if (skip) {
+    printInfo(MESSAGES.HOOK_SKIPPED);
+    return;
+  }
+
+  // 解析 hook 配置
+  const hook = resolvePostCreateHook();
+  if (!hook) {
+    printInfo(MESSAGES.HOOK_NOT_CONFIGURED);
+    return;
+  }
+
+  // 输出 hook 来源
+  printInfo(MESSAGES.HOOK_SOURCE_INFO(getSourceLabel(hook)));
+  printInfo('');
+
+  // 提示用户 hook 正在后台执行
+  printInfo(MESSAGES.HOOK_BACKGROUND_START(worktrees.length, hook.command));
+
+  // fire-and-forget：后台异步并行执行，不 await
+  executePostCreateHooks(worktrees, hook).then((results) => {
+    // 汇总日志
+    const succeeded = results.filter((r) => r.success).length;
+    const failed = results.filter((r) => !r.success).length;
+    logger.info(`postCreate hook 汇总: ${succeeded} 成功, ${failed} 失败`);
+  }).catch((err) => {
+    // 兜底：不应到达此分支，但确保不影响主流程
+    logger.error(`postCreate hook 执行异常: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}

package/src/types/command.ts

@@ -4,6 +4,8 @@ export interface CreateOptions {
   branch: string;
   /** 创建数量（Commander 传入为字符串），默认 '1' */
   number: string;
+  /** 是否执行 postCreate hook，--no-post-create 时为 false */
+  postCreate?: boolean;
 }
 
 /** run 命令选项 */
@@ -18,6 +20,8 @@ export interface RunOptions {
   file?: string;
   /** 预览模式，仅展示任务计划不实际执行 */
   dryRun?: boolean;
+  /** 是否执行 postCreate hook，--no-post-create 时为 false */
+  postCreate?: boolean;
 }
 
 /** validate 命令选项 */

package/src/types/index.ts

@@ -7,3 +7,4 @@ export type { WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, Snapshot
 export type { TaskFileEntry, ParseTaskFileOptions } from './taskFile.js';
 export type { ProjectOverview, ProjectWorktreeDetail, ProjectDetailResult, ProjectsOverviewResult } from './project.js';
 export type { ProjectConfig, ProjectConfigItemDefinition, ProjectConfigDefinitions } from './projectConfig.js';
+export type { PostCreateHookSource, PostCreateHookResult, ResolvedHook } from './postCreateHook.js';

package/src/types/postCreateHook.ts

@@ -0,0 +1,24 @@
+/** postCreate hook 的来源 */
+export type PostCreateHookSource = 'projectConfig' | 'postCreateScript';
+
+/** 单个 worktree 的 hook 执行结果 */
+export interface PostCreateHookResult {
+  /** worktree 绝对路径 */
+  worktreePath: string;
+  /** 分支名 */
+  branch: string;
+  /** 是否执行成功 */
+  success: boolean;
+  /** hook 来源 */
+  source: PostCreateHookSource;
+  /** 失败时的错误信息 */
+  error?: string;
+}
+
+/** hook 解析结果 */
+export interface ResolvedHook {
+  /** 待执行的命令 */
+  command: string;
+  /** hook 来源 */
+  source: PostCreateHookSource;
+}

package/src/types/projectConfig.ts

@@ -4,6 +4,8 @@ export interface ProjectConfig {
   clawtMainWorkBranch: string;
   /** validate 成功后自动执行的命令（-r 的默认值） */
   validateRunCommand?: string;
+  /** worktree 创建后自动执行的命令，用于安装依赖等初始化操作 */
+  postCreate?: string;
 }
 
 /** 单个项目配置项的完整定义（默认值 + 描述） */