clawt 3.7.1 → 3.8.0

package/.clawt/postCreate.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+pnpm install --frozen-lockfile

package/CLAUDE.md

@@ -1,5 +1,15 @@
 # Project Memory
 
+## 代码阅读规范（必须严格遵守的三步阅读流程）
+
+每次接到任务时，**必须**按以下顺序渐进式地理解项目，禁止跳步：
+
+1. **第一步：阅读 `docs/spec.md`** — 全面了解项目整体架构、核心概念与模块划分，建立全局认知。
+2. **第二步：根据用户问题，阅读 `docs/` 下对应模块的详细文档** — 例如用户问 merge 相关功能，则阅读 `docs/merge.md`；问 config 相关则阅读 `docs/config.md` 和 `docs/config-file.md`，以此类推。
+3. **第三步：阅读具体的源代码** — 在前两步建立充分上下文后，再深入代码实现，确保方案设计不会因阅读代码不全面而产生缺陷。
+
+>  **重要提示：文档可能滞后于代码。当文档描述与实际代码实现存在冲突时，以代码为准。**
+
 ## 编码规范
 
 - JSON 序列化必须使用项目封装的 `safeStringify`（位于 `src/utils/json.ts`），禁止直接使用原生 `JSON.stringify`。`safeStringify` 已通过 `src/utils/index.js` 统一导出。

package/README.md

@@ -54,7 +54,7 @@ clawt init show           # 交互式查看和修改项目配置
 clawt init show --json    # 以 JSON 格式输出项目配置
 ```
 
-设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令）。`init show --json` 可以直接输出当前项目配置的 JSON 格式。
+设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令、worktree 创建后自动执行的 postCreate hook 命令等）。`init show --json` 可以直接输出当前项目配置的 JSON 格式。
 
 ### `clawt run` — 创建 worktree 并执行任务
 
@@ -73,6 +73,9 @@ clawt run -f tasks.md -b feat
 
 # 试运行：仅预览将要创建的 worktree 和任务，不实际执行
 clawt run -b <branch> --tasks "任务1" --tasks "任务2" --dry-run
+
+# 跳过 postCreate hook
+clawt run -b <branch> --no-post-create
 ```
 
 **`--dry-run` 预览示例：**
@@ -139,6 +142,7 @@ clawt resume -f tasks.md -c 2  # 限制并发数
 ```bash
 clawt create -b <branch>           # 创建 1 个
 clawt create -b <branch> -n 3      # 批量创建 3 个
+clawt create -b <branch> --no-post-create  # 跳过 postCreate hook
 ```
 
 ### `clawt validate` — 在主 worktree 中验证分支变更
@@ -337,6 +341,19 @@ clawt alias remove l
 | `conflictResolveMode` | `"ask"` | merge 冲突时的解决模式：`ask`（询问是否使用 AI）、`auto`（自动 AI 解决）、`manual`（手动解决） |
 | `conflictResolveTimeoutMs` | `300000` | Claude Code 冲突解决超时时间（毫秒），默认 5 分钟 |
 
+## postCreate Hook
+
+worktree 创建后可自动执行任意初始化命令（如安装依赖、生成配置文件、编译资源等），`create` 和 `run` 命令均支持。
+
+**配置方式（二选一）：**
+
+1. **项目配置**：通过 `clawt init show` 设置 `postCreate` 字段（如 `npm install`）
+2. **脚本文件**：在项目根目录创建 `.clawt/postCreate.sh` 并赋予执行权限
+
+项目配置优先于脚本文件。使用 `--no-post-create` 可跳过 hook 执行。
+
+hook 以 fire-and-forget 模式后台异步并行执行，不阻塞主流程。执行结果仅写入日志。
+
 ## 全局选项
 
 | 选项 | 说明 |

package/dist/index.js

@@ -564,6 +564,30 @@ var TASKS_CMD_MESSAGES = {
   TASK_INIT_HINT: (path2) => `\u4F7F\u7528 clawt run -f ${path2} \u6267\u884C\u4EFB\u52A1`
 };
 
+// src/constants/messages/post-create.ts
+var POST_CREATE_MESSAGES = {
+  /** hook 执行跳过（--no-post-create） */
+  HOOK_SKIPPED: "\u5DF2\u8DF3\u8FC7 postCreate hook\uFF08--no-post-create\uFF09",
+  /** 无 hook 配置 */
+  HOOK_NOT_CONFIGURED: "\u672A\u914D\u7F6E postCreate hook\uFF0C\u8DF3\u8FC7",
+  /** hook 来源提示 */
+  HOOK_SOURCE_INFO: (source) => `postCreate hook \u6765\u6E90: ${source}`,
+  /** hook 开始执行 */
+  HOOK_EXECUTING: (branch, command) => `[${branch}] \u6B63\u5728\u6267\u884C postCreate hook: ${command}`,
+  /** hook 执行成功 */
+  HOOK_SUCCESS: (branch) => `[${branch}] postCreate hook \u6267\u884C\u6210\u529F`,
+  /** hook 执行失败 */
+  HOOK_FAILED: (branch, error) => `[${branch}] postCreate hook \u6267\u884C\u5931\u8D25: ${error}`,
+  /** hook 执行汇总 */
+  HOOK_SUMMARY: (succeeded, failed) => `postCreate hook \u6267\u884C\u5B8C\u6210: ${succeeded} \u6210\u529F, ${failed} \u5931\u8D25`,
+  /** hook 后台执行中提示 */
+  HOOK_BACKGROUND_START: (count, command) => `postCreate hook \u6B63\u5728\u540E\u53F0\u6267\u884C (${count} \u4E2A worktree): ${command}`,
+  /** postCreate.sh 自动添加执行权限 */
+  POST_CREATE_SCRIPT_AUTO_CHMOD: (path2) => `${path2} \u4E0D\u53EF\u6267\u884C\uFF0C\u5DF2\u81EA\u52A8\u6DFB\u52A0\u6267\u884C\u6743\u9650`,
+  /** postCreate.sh 不可执行（自动 chmod 失败时降级提示） */
+  POST_CREATE_SCRIPT_NOT_EXECUTABLE: (path2) => `\u68C0\u6D4B\u5230 ${path2} \u4F46\u4E0D\u53EF\u6267\u884C\uFF0C\u81EA\u52A8\u6DFB\u52A0\u6743\u9650\u5931\u8D25\uFF0C\u8BF7\u624B\u52A8\u6267\u884C chmod +x ${path2}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -652,7 +676,8 @@ var MESSAGES = {
   ...INIT_MESSAGES,
   ...COVER_VALIDATE_MESSAGES,
   ...HOME_MESSAGES,
-  ...TASKS_CMD_MESSAGES
+  ...TASKS_CMD_MESSAGES,
+  ...POST_CREATE_MESSAGES
 };
 
 // src/constants/exitCodes.ts
@@ -670,7 +695,7 @@ var VALID_TERMINAL_APPS = ["auto", "iterm2", "terminal"];
 var ITERM2_APP_PATH = "/Applications/iTerm.app";
 
 // src/constants/config.ts
-var 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.";
+var APPEND_SYSTEM_PROMPT = "Currently, you are in the git worktree directory.";
 var CONFIG_DEFINITIONS = {
   autoDeleteBranch: {
     defaultValue: false,
@@ -743,6 +768,10 @@ var PROJECT_CONFIG_DEFINITIONS = {
   validateRunCommand: {
     defaultValue: void 0,
     description: "validate \u6210\u529F\u540E\u81EA\u52A8\u6267\u884C\u7684\u547D\u4EE4\uFF08-r \u7684\u9ED8\u8BA4\u503C\uFF09"
+  },
+  postCreate: {
+    defaultValue: void 0,
+    description: "worktree \u521B\u5EFA\u540E\u81EA\u52A8\u6267\u884C\u7684\u547D\u4EE4\uFF0C\u7528\u4E8E\u5B89\u88C5\u4F9D\u8D56\u7B49\u521D\u59CB\u5316\u64CD\u4F5C"
   }
 };
 function deriveDefaultConfig2(definitions) {
@@ -2020,8 +2049,9 @@ function escapeShellSingleQuote(str) {
 }
 function buildClaudeCommand(worktree, hasPreviousSession) {
   const commandStr = getConfigValue("claudeCodeCommand");
+  const systemPrompt = APPEND_SYSTEM_PROMPT;
   const escapedPath = escapeShellSingleQuote(worktree.path);
-  const escapedPrompt = escapeShellSingleQuote(APPEND_SYSTEM_PROMPT);
+  const escapedPrompt = escapeShellSingleQuote(systemPrompt);
   const continueFlag = hasPreviousSession ? " --continue" : "";
   return `cd '${escapedPath}' && ${commandStr} --append-system-prompt '${escapedPrompt}'${continueFlag}`;
 }
@@ -2841,7 +2871,8 @@ function parseStreamEvent(event) {
 
 // src/utils/task-executor.ts
 function executeClaudeTask(worktree, task, onActivity, continueSession) {
-  const args = ["-p", task, "--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions"];
+  const systemPrompt = APPEND_SYSTEM_PROMPT;
+  const args = ["-p", task, "--output-format", "stream-json", "--verbose", "--permission-mode", "bypassPermissions", "--append-system-prompt", systemPrompt];
   if (continueSession) {
     args.push("--continue");
   }
@@ -4326,6 +4357,117 @@ async function handleMergeConflict(currentBranch, incomingBranch, cwd, autoFlag)
   return resolveConflictsWithAI(currentBranch, incomingBranch, cwd);
 }
 
+// src/hooks/post-create.ts
+import { existsSync as existsSync10, accessSync, chmodSync, constants as fsConstants } from "fs";
+import { spawn as spawn2 } from "child_process";
+import { join as join8 } from "path";
+var POST_CREATE_SCRIPT_RELATIVE_PATH = ".clawt/postCreate.sh";
+function isExecutable(filePath) {
+  try {
+    accessSync(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function autoFixExecutablePermission(filePath) {
+  try {
+    chmodSync(filePath, 493);
+    printInfo(MESSAGES.POST_CREATE_SCRIPT_AUTO_CHMOD(filePath));
+  } catch {
+    printWarning(MESSAGES.POST_CREATE_SCRIPT_NOT_EXECUTABLE(filePath));
+  }
+}
+function normalizeCommand(value) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+function resolvePostCreateHook() {
+  const config2 = loadProjectConfig();
+  if (config2?.postCreate) {
+    const command = normalizeCommand(config2.postCreate);
+    if (command) {
+      return { command, source: "projectConfig" };
+    }
+  }
+  const mainWorktreePath = getMainWorktreePath();
+  const scriptPath = join8(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
+  if (existsSync10(scriptPath)) {
+    if (!isExecutable(scriptPath)) {
+      autoFixExecutablePermission(scriptPath);
+    }
+    return { command: scriptPath, source: "postCreateScript" };
+  }
+  return null;
+}
+function getSourceLabel(hook) {
+  return hook.source === "projectConfig" ? "\u9879\u76EE\u914D\u7F6E (postCreate)" : ".clawt/postCreate.sh";
+}
+function executeOneHook(worktree, hook) {
+  return new Promise((resolve4) => {
+    const result = {
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      success: true,
+      source: hook.source
+    };
+    try {
+      const child = spawn2(hook.command, {
+        cwd: worktree.path,
+        stdio: "ignore",
+        shell: true
+      });
+      child.on("error", (err) => {
+        result.success = false;
+        result.error = err.message;
+        logger.error(`postCreate hook \u5F02\u5E38: ${hook.command} @ ${worktree.path}: ${result.error}`);
+        resolve4(result);
+      });
+      child.on("close", (code) => {
+        if (code !== null && code !== 0) {
+          result.success = false;
+          result.error = `\u547D\u4EE4\u9000\u51FA\u7801: ${code}`;
+          logger.error(`postCreate hook \u5931\u8D25: ${hook.command} (\u9000\u51FA\u7801: ${code}) @ ${worktree.path}`);
+        } else {
+          logger.info(`postCreate hook \u6210\u529F: ${hook.command} @ ${worktree.path}`);
+        }
+        resolve4(result);
+      });
+    } catch (err) {
+      result.success = false;
+      result.error = err instanceof Error ? err.message : String(err);
+      logger.error(`postCreate hook \u542F\u52A8\u5931\u8D25: ${hook.command} @ ${worktree.path}: ${result.error}`);
+      resolve4(result);
+    }
+  });
+}
+function executePostCreateHooks(worktrees, hook) {
+  const promises = worktrees.map((worktree) => executeOneHook(worktree, hook));
+  return Promise.all(promises);
+}
+function runPostCreateHooks(worktrees, skip) {
+  if (skip) {
+    printInfo(MESSAGES.HOOK_SKIPPED);
+    return;
+  }
+  const hook = resolvePostCreateHook();
+  if (!hook) {
+    printInfo(MESSAGES.HOOK_NOT_CONFIGURED);
+    return;
+  }
+  printInfo(MESSAGES.HOOK_SOURCE_INFO(getSourceLabel(hook)));
+  printInfo("");
+  printInfo(MESSAGES.HOOK_BACKGROUND_START(worktrees.length, hook.command));
+  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 \u6C47\u603B: ${succeeded} \u6210\u529F, ${failed} \u5931\u8D25`);
+  }).catch((err) => {
+    logger.error(`postCreate hook \u6267\u884C\u5F02\u5E38: ${err instanceof Error ? err.message : String(err)}`);
+  });
+}
+
 // src/commands/list.ts
 import chalk10 from "chalk";
 function registerListCommand(program2) {
@@ -4379,7 +4521,7 @@ function printListAsText(projectName, worktrees) {
 
 // src/commands/create.ts
 function registerCreateCommand(program2) {
-  program2.command("create").description("\u6279\u91CF\u521B\u5EFA worktree \u53CA\u5BF9\u5E94\u5206\u652F\uFF08\u542B\u9A8C\u8BC1\u5206\u652F\uFF09").requiredOption("-b, --branch <branchName>", "\u5206\u652F\u540D").option("-n, --number <count>", "\u521B\u5EFA\u6570\u91CF", "1").action(async (options) => {
+  program2.command("create").description("\u6279\u91CF\u521B\u5EFA worktree \u53CA\u5BF9\u5E94\u5206\u652F\uFF08\u542B\u9A8C\u8BC1\u5206\u652F\uFF09").requiredOption("-b, --branch <branchName>", "\u5206\u652F\u540D").option("-n, --number <count>", "\u521B\u5EFA\u6570\u91CF", "1").option("--post-create", "\u6267\u884C postCreate hook\uFF08\u9ED8\u8BA4\u5F00\u542F\uFF0C--no-post-create \u8DF3\u8FC7\uFF09", true).action(async (options) => {
     await handleCreate(options);
   });
 }
@@ -4394,6 +4536,7 @@ async function handleCreate(options) {
   }
   logger.info(`create \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u6570\u91CF: ${count}`);
   const worktrees = createWorktrees(options.branch, count);
+  runPostCreateHooks(worktrees, !options.postCreate);
   printSuccess(MESSAGES.WORKTREE_CREATED(worktrees.length));
   printInfo("");
   worktrees.forEach((wt, index) => {
@@ -4487,7 +4630,7 @@ async function handleRemove(options) {
 
 // src/commands/run.ts
 function registerRunCommand(program2) {
-  program2.command("run").description("\u6279\u91CF\u521B\u5EFA worktree + \u542F\u52A8 Claude Code \u6267\u884C\u4EFB\u52A1\uFF08\u652F\u6301\u4EFB\u52A1\u6587\u4EF6\uFF09").option("-b, --branch <branchName>", "\u5206\u652F\u540D").option("--tasks <task...>", "\u4EFB\u52A1\u5217\u8868\uFF08\u53EF\u591A\u6B21\u6307\u5B9A\uFF09\uFF0C\u4E0D\u4F20\u5219\u5728 worktree \u4E2D\u6253\u5F00 Claude Code \u4EA4\u4E92\u5F0F\u754C\u9762").option("-c, --concurrency <n>", "\u6700\u5927\u5E76\u53D1\u6570\uFF0C0 \u8868\u793A\u4E0D\u9650\u5236").option("-f, --file <path>", "\u4ECE\u4EFB\u52A1\u6587\u4EF6\u8BFB\u53D6\u4EFB\u52A1\u5217\u8868\uFF08\u4E0E --tasks \u4E92\u65A5\uFF09").option("--dry-run", "\u9884\u89C8\u6A21\u5F0F\uFF0C\u4EC5\u5C55\u793A\u4EFB\u52A1\u8BA1\u5212\u4E0D\u5B9E\u9645\u6267\u884C").action(async (options) => {
+  program2.command("run").description("\u6279\u91CF\u521B\u5EFA worktree + \u542F\u52A8 Claude Code \u6267\u884C\u4EFB\u52A1\uFF08\u652F\u6301\u4EFB\u52A1\u6587\u4EF6\uFF09").option("-b, --branch <branchName>", "\u5206\u652F\u540D").option("--tasks <task...>", "\u4EFB\u52A1\u5217\u8868\uFF08\u53EF\u591A\u6B21\u6307\u5B9A\uFF09\uFF0C\u4E0D\u4F20\u5219\u5728 worktree \u4E2D\u6253\u5F00 Claude Code \u4EA4\u4E92\u5F0F\u754C\u9762").option("-c, --concurrency <n>", "\u6700\u5927\u5E76\u53D1\u6570\uFF0C0 \u8868\u793A\u4E0D\u9650\u5236").option("-f, --file <path>", "\u4ECE\u4EFB\u52A1\u6587\u4EF6\u8BFB\u53D6\u4EFB\u52A1\u5217\u8868\uFF08\u4E0E --tasks \u4E92\u65A5\uFF09").option("--dry-run", "\u9884\u89C8\u6A21\u5F0F\uFF0C\u4EC5\u5C55\u793A\u4EFB\u52A1\u8BA1\u5212\u4E0D\u5B9E\u9645\u6267\u884C").option("--post-create", "\u6267\u884C postCreate hook\uFF08\u9ED8\u8BA4\u5F00\u542F\uFF0C--no-post-create \u8DF3\u8FC7\uFF09", true).action(async (options) => {
     await handleRun(options);
   });
 }
@@ -4510,6 +4653,7 @@ async function handleRunFromFile(options) {
     const branches = entries.map((e) => sanitizeBranchName(e.branch));
     worktrees = createWorktreesByBranches(branches);
   }
+  runPostCreateHooks(worktrees, !options.postCreate);
   const concurrency = parseConcurrency(options.concurrency, getConfigValue("maxConcurrency"));
   logger.info(`run \u547D\u4EE4\uFF08\u6587\u4EF6\u6A21\u5F0F\uFF09\u6267\u884C\uFF0C\u4EFB\u52A1\u6570: ${entries.length}\uFF0C\u5E76\u53D1\u6570: ${concurrency || "\u4E0D\u9650\u5236"}`);
   await executeBatchTasks(worktrees, tasks, concurrency);
@@ -4561,6 +4705,7 @@ async function handleRun(options) {
     }
     const worktrees2 = createWorktrees(options.branch, 1);
     const worktree = worktrees2[0];
+    runPostCreateHooks(worktrees2, !options.postCreate);
     printSuccess(MESSAGES.WORKTREE_CREATED(1));
     launchInteractiveClaude(worktree);
     return;
@@ -4570,6 +4715,7 @@ async function handleRun(options) {
   const concurrency = parseConcurrency(options.concurrency, getConfigValue("maxConcurrency"));
   logger.info(`run \u547D\u4EE4\u6267\u884C\uFF0C\u5206\u652F: ${options.branch}\uFF0C\u4EFB\u52A1\u6570: ${count}\uFF0C\u5E76\u53D1\u6570: ${concurrency || "\u4E0D\u9650\u5236"}`);
   const worktrees = createWorktrees(options.branch, count);
+  runPostCreateHooks(worktrees, !options.postCreate);
   await executeBatchTasks(worktrees, tasks, concurrency);
 }
 
@@ -5460,8 +5606,8 @@ function registerAliasCommand(program2) {
 }
 
 // src/commands/projects.ts
-import { existsSync as existsSync10, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
-import { join as join8 } from "path";
+import { existsSync as existsSync11, readdirSync as readdirSync5, statSync as statSync4 } from "fs";
+import { join as join9 } from "path";
 import chalk13 from "chalk";
 function registerProjectsCommand(program2) {
   program2.command("projects [name]").description("\u5C55\u793A\u6240\u6709\u9879\u76EE\u7684 worktree \u6982\u89C8\uFF0C\u6216\u67E5\u770B\u6307\u5B9A\u9879\u76EE\u7684 worktree \u8BE6\u60C5").option("--json", "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((name, options) => {
@@ -5485,8 +5631,8 @@ function handleProjectsOverview(json) {
   printProjectsOverviewAsText(result);
 }
 function handleProjectDetail(name, json) {
-  const projectDir = join8(WORKTREES_DIR, name);
-  if (!existsSync10(projectDir)) {
+  const projectDir = join9(WORKTREES_DIR, name);
+  if (!existsSync11(projectDir)) {
     printError(MESSAGES.PROJECTS_NOT_FOUND(name));
     process.exit(1);
   }
@@ -5499,7 +5645,7 @@ function handleProjectDetail(name, json) {
   printProjectDetailAsText(result);
 }
 function collectProjectsOverview() {
-  if (!existsSync10(WORKTREES_DIR)) {
+  if (!existsSync11(WORKTREES_DIR)) {
     return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
   }
   const entries = readdirSync5(WORKTREES_DIR, { withFileTypes: true });
@@ -5508,7 +5654,7 @@ function collectProjectsOverview() {
     if (!entry.isDirectory()) {
       continue;
     }
-    const projectDir = join8(WORKTREES_DIR, entry.name);
+    const projectDir = join9(WORKTREES_DIR, entry.name);
     const overview = collectSingleProjectOverview(entry.name, projectDir);
     projects.push(overview);
   }
@@ -5525,7 +5671,7 @@ function collectSingleProjectOverview(name, projectDir) {
   const worktreeDirs = subEntries.filter((e) => e.isDirectory());
   const worktreeCount = worktreeDirs.length;
   const diskUsage = calculateDirSize(projectDir);
-  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join8(projectDir, e.name)));
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join9(projectDir, e.name)));
   return {
     name,
     worktreeCount,
@@ -5540,7 +5686,7 @@ function collectProjectDetail(name, projectDir) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const wtPath = join8(projectDir, entry.name);
+    const wtPath = join9(projectDir, entry.name);
     const detail = collectSingleWorktreeDetail(entry.name, wtPath);
     worktrees.push(detail);
   }
@@ -5639,7 +5785,7 @@ function printWorktreeDetailItem(wt) {
 }
 
 // src/commands/completion.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync12 } from "fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync13 } from "fs";
 import { resolve as resolve2 } from "path";
 import { homedir as homedir2 } from "os";
 
@@ -5690,14 +5836,14 @@ compdef _clawt_completion clawt
 }
 
 // src/utils/completion-engine.ts
-import { existsSync as existsSync11, readdirSync as readdirSync6, statSync as statSync5 } from "fs";
-import { join as join9, dirname, basename as basename2 } from "path";
+import { existsSync as existsSync12, readdirSync as readdirSync6, statSync as statSync5 } from "fs";
+import { join as join10, dirname, basename as basename2 } from "path";
 function completeFilePath(partial) {
   const cwd = process.cwd();
   const hasDir = partial.includes("/");
-  const searchDir = hasDir ? join9(cwd, dirname(partial)) : cwd;
+  const searchDir = hasDir ? join10(cwd, dirname(partial)) : cwd;
   const prefix = hasDir ? basename2(partial) : partial;
-  if (!existsSync11(searchDir)) {
+  if (!existsSync12(searchDir)) {
     return [];
   }
   const entries = readdirSync6(searchDir);
@@ -5706,7 +5852,7 @@ function completeFilePath(partial) {
   for (const entry of entries) {
     if (!entry.startsWith(prefix)) continue;
     if (entry.startsWith(".")) continue;
-    const fullPath = join9(searchDir, entry);
+    const fullPath = join10(searchDir, entry);
     try {
       const stat = statSync5(fullPath);
       if (stat.isDirectory()) {
@@ -5795,7 +5941,7 @@ function generateCompletions(program2, args) {
 
 // src/commands/completion.ts
 function appendToFile(filePath, content) {
-  if (existsSync12(filePath)) {
+  if (existsSync13(filePath)) {
     const current = readFileSync6(filePath, "utf-8");
     if (current.includes("clawt completion")) {
       printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ": " + filePath);
@@ -5930,19 +6076,19 @@ async function handleHome() {
 }
 
 // src/commands/tasks.ts
-import { resolve as resolve3, dirname as dirname2, join as join10 } from "path";
-import { existsSync as existsSync13, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve3, dirname as dirname2, join as join11 } from "path";
+import { existsSync as existsSync14, writeFileSync as writeFileSync6 } from "fs";
 function registerTasksCommand(program2) {
   const taskCmd = program2.command("tasks").description("\u4EFB\u52A1\u6587\u4EF6\u7BA1\u7406");
   taskCmd.command("init").description("\u751F\u6210\u4EFB\u52A1\u6A21\u677F\u6587\u4EF6").argument("[path]", "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (path2) => {
-    const filePath = path2 ?? join10(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
+    const filePath = path2 ?? join11(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
     await handleTasksInit(filePath);
   });
 }
 async function handleTasksInit(filePath) {
   const absolutePath = resolve3(filePath);
   logger.info(`tasks init \u547D\u4EE4\u6267\u884C\uFF0C\u76EE\u6807\u6587\u4EF6: ${absolutePath}`);
-  if (existsSync13(absolutePath)) {
+  if (existsSync14(absolutePath)) {
     throw new ClawtError(MESSAGES.TASK_INIT_FILE_EXISTS(filePath));
   }
   ensureDir(dirname2(absolutePath));

package/dist/postinstall.js

@@ -541,6 +541,30 @@ var TASKS_CMD_MESSAGES = {
   TASK_INIT_HINT: (path) => `\u4F7F\u7528 clawt run -f ${path} \u6267\u884C\u4EFB\u52A1`
 };
 
+// src/constants/messages/post-create.ts
+var POST_CREATE_MESSAGES = {
+  /** hook 执行跳过（--no-post-create） */
+  HOOK_SKIPPED: "\u5DF2\u8DF3\u8FC7 postCreate hook\uFF08--no-post-create\uFF09",
+  /** 无 hook 配置 */
+  HOOK_NOT_CONFIGURED: "\u672A\u914D\u7F6E postCreate hook\uFF0C\u8DF3\u8FC7",
+  /** hook 来源提示 */
+  HOOK_SOURCE_INFO: (source) => `postCreate hook \u6765\u6E90: ${source}`,
+  /** hook 开始执行 */
+  HOOK_EXECUTING: (branch, command) => `[${branch}] \u6B63\u5728\u6267\u884C postCreate hook: ${command}`,
+  /** hook 执行成功 */
+  HOOK_SUCCESS: (branch) => `[${branch}] postCreate hook \u6267\u884C\u6210\u529F`,
+  /** hook 执行失败 */
+  HOOK_FAILED: (branch, error) => `[${branch}] postCreate hook \u6267\u884C\u5931\u8D25: ${error}`,
+  /** hook 执行汇总 */
+  HOOK_SUMMARY: (succeeded, failed) => `postCreate hook \u6267\u884C\u5B8C\u6210: ${succeeded} \u6210\u529F, ${failed} \u5931\u8D25`,
+  /** hook 后台执行中提示 */
+  HOOK_BACKGROUND_START: (count, command) => `postCreate hook \u6B63\u5728\u540E\u53F0\u6267\u884C (${count} \u4E2A worktree): ${command}`,
+  /** postCreate.sh 自动添加执行权限 */
+  POST_CREATE_SCRIPT_AUTO_CHMOD: (path) => `${path} \u4E0D\u53EF\u6267\u884C\uFF0C\u5DF2\u81EA\u52A8\u6DFB\u52A0\u6267\u884C\u6743\u9650`,
+  /** postCreate.sh 不可执行（自动 chmod 失败时降级提示） */
+  POST_CREATE_SCRIPT_NOT_EXECUTABLE: (path) => `\u68C0\u6D4B\u5230 ${path} \u4F46\u4E0D\u53EF\u6267\u884C\uFF0C\u81EA\u52A8\u6DFB\u52A0\u6743\u9650\u5931\u8D25\uFF0C\u8BF7\u624B\u52A8\u6267\u884C chmod +x ${path}`
+};
+
 // src/constants/messages/interactive-panel.ts
 import chalk from "chalk";
 
@@ -600,7 +624,8 @@ var MESSAGES = {
   ...INIT_MESSAGES,
   ...COVER_VALIDATE_MESSAGES,
   ...HOME_MESSAGES,
-  ...TASKS_CMD_MESSAGES
+  ...TASKS_CMD_MESSAGES,
+  ...POST_CREATE_MESSAGES
 };
 
 // src/constants/terminal.ts
@@ -679,6 +704,10 @@ var PROJECT_CONFIG_DEFINITIONS = {
   validateRunCommand: {
     defaultValue: void 0,
     description: "validate \u6210\u529F\u540E\u81EA\u52A8\u6267\u884C\u7684\u547D\u4EE4\uFF08-r \u7684\u9ED8\u8BA4\u503C\uFF09"
+  },
+  postCreate: {
+    defaultValue: void 0,
+    description: "worktree \u521B\u5EFA\u540E\u81EA\u52A8\u6267\u884C\u7684\u547D\u4EE4\uFF0C\u7528\u4E8E\u5B89\u88C5\u4F9D\u8D56\u7B49\u521D\u59CB\u5316\u64CD\u4F5C"
   }
 };
 function deriveDefaultConfig2(definitions) {

package/docs/create.md

@@ -3,7 +3,7 @@
 **命令：**
 
 ```bash
-clawt create -b <branchName> [-n <count>]
+clawt create -b <branchName> [-n <count>] [--no-post-create]
 ```
 
 **参数：**
@@ -12,6 +12,7 @@ clawt create -b <branchName> [-n <count>]
 | ---- | ---- | ----------------------------------------------------- |
 | `-b, --branch` | 是   | 分支名                                                |
 | `-n, --number` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
+| `--post-create` | 否   | 执行 postCreate hook（默认开启，`--no-post-create` 跳过）。详见 [post-create-hook.md](./post-create-hook.md) |
 
 **运行流程：**
 
@@ -64,7 +65,8 @@ clawt create -b <branchName> [-n <count>]
      git worktree add -b <branchName>-n ~/.clawt/worktrees/<project>/<branchName>-n
      git branch clawt-validate-<branchName>-n
      ```
-9. **输出创建日志**
+9. **执行 postCreate hook**：调用 `runPostCreateHooks(worktrees, !options.postCreate)` 以 fire-and-forget 模式后台异步并行执行 postCreate hook（用户自定义的初始化操作）。`--no-post-create` 时跳过。详见 [post-create-hook.md](./post-create-hook.md)
+10. **输出创建日志**
 
 **输出格式：**
 
@@ -97,5 +99,7 @@ clawt create -b <branchName> [-n <count>]
 - 确保在主工作分支的逻辑在 `src/utils/validate-branch.ts` 的 `ensureOnMainWorkBranch` 中
 - 脏工作区交互处理逻辑在 `src/utils/validate-branch.ts` 的 `handleDirtyWorkingDir` 中
 - 相关消息常量定义在 `src/constants/messages/create.ts` 和 `src/constants/messages/common.ts` 中
+- postCreate hook 执行逻辑在 `src/hooks/post-create.ts` 中，通过 `src/utils/index.js` 统一导出 `runPostCreateHooks`
+- hook 相关消息常量定义在 `src/constants/messages/post-create.ts` 中
 
 ---

package/docs/init.md

@@ -26,7 +26,7 @@ clawt init show --json
 
 **功能说明：**
 
-初始化项目级配置，将指定分支记录为该项目的主工作分支（`clawtMainWorkBranch`）。该配置用于 `create` / `run` 时检测当前分支是否为主工作分支，并在偏离时提醒用户。`init show` 子命令提供交互式面板，可查看和修改所有项目配置项（如 `validateRunCommand`）。项目级配置的完整说明见 [project-config.md](./project-config.md)。
+初始化项目级配置，将指定分支记录为该项目的主工作分支（`clawtMainWorkBranch`）。该配置用于 `create` / `run` 时检测当前分支是否为主工作分支，并在偏离时提醒用户。`init show` 子命令提供交互式面板，可查看和修改所有项目配置项（如 `validateRunCommand`、`postCreate`）。项目级配置的完整说明见 [project-config.md](./project-config.md)。
 
 **运行流程（设置模式）：**
 
@@ -69,7 +69,7 @@ clawt init show --json
 ✓ 项目配置 validateRunCommand 已设置为 npm test
 
 # show --json 输出
-{"clawtMainWorkBranch":"main","validateRunCommand":"npm test"}
+{"clawtMainWorkBranch":"main","validateRunCommand":"npm test","postCreate":"npm install"}
 
 # show 未初始化（抛出错误）
 项目尚未初始化，请先执行 clawt init 设置主工作分支