npm - clawt - Versions diffs - 3.8.3 → 3.8.5 - Mend

clawt 3.8.3 → 3.8.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +177 -175
package/README.zh-CN.md +379 -0
package/dist/index.js +10 -54
package/dist/postinstall.js +2 -0
package/docs/remove.md +2 -2
package/package.json +1 -1
package/src/commands/home.ts +1 -1
package/src/constants/messages/common.ts +2 -0
package/src/utils/validation.ts +11 -13
package/src/utils/worktree-matcher.ts +3 -3
package/tests/unit/constants/messages.test.ts +1 -0
package/tests/unit/utils/validation.test.ts +13 -6

package/README.md CHANGED Viewed

@@ -1,377 +1,379 @@
 # Clawt
-基于 Git Worktree 并行执行多个 Claude Code Agent 任务，所有 Agent 的代码修改互不干扰。
+**[English](./README.md)** | [中文](./README.zh-CN.md)
-## 安装
+Run multiple Claude Code Agent tasks in parallel based on Git Worktree — all agents' code changes are fully isolated from each other.
+## Installation
 ```bash
 npm i -g clawt
 ```
-**环境要求：** Node.js >= 18 · Git >= 2.15 · Claude Code CLI
+**Requirements:** Node.js >= 18 · Git >= 2.15 · Claude Code CLI
-## 快速开始
+## Quick Start
 ```bash
-# 1. 在项目根目录（包含 .git 的目录）下初始化，确认主工作分支
+# 1. Initialize in your project root (directory containing .git), confirm the main work branch
 clawt init
-# 2. 并行执行任务，每个任务在独立的 worktree 中运行
+# 2. Run tasks in parallel, each in its own isolated worktree
 clawt run -b feat-login
 clawt run -b feat-search
 clawt run -b fix-bug
-# 3. 打开交互式面板，实时查看所有任务状态，一站式完成后续操作
+# 3. Open the interactive panel to monitor all task statuses and perform actions
 clawt status -i
 ```
-`clawt status -i` 提供实时刷新的 TUI 面板，用方向键选中 worktree 后可直接按快捷键操作：
+`clawt status -i` provides a real-time TUI panel. Use arrow keys to select a worktree, then press shortcuts to operate:
-| 快捷键 | 操作 | 等同命令 |
+| Shortcut | Action | Equivalent Command |
 | ------ | ---- | -------- |
-| `v` | 验证分支变更 | `clawt validate -b <branch>` |
-| `m` | 合并到主分支 | `clawt merge -b <branch>` |
-| `r` | 恢复 Claude Code 会话 | `clawt resume -b <branch>` |
-| `s` | 同步主分支代码 | `clawt sync -b <branch>` |
-| `d` | 删除 worktree | `clawt remove -b <branch>` |
-| `c` | 覆盖修改回目标 worktree | `clawt cover` |
-| `q` | 退出面板 | — |
-示例：
+| `v` | Validate branch changes | `clawt validate -b <branch>` |
+| `m` | Merge into main branch | `clawt merge -b <branch>` |
+| `r` | Resume Claude Code session | `clawt resume -b <branch>` |
+| `s` | Sync main branch code | `clawt sync -b <branch>` |
+| `d` | Delete worktree | `clawt remove -b <branch>` |
+| `c` | Cover changes back to target worktree | `clawt cover` |
+| `q` | Quit panel | — |
+Example:
 ![](https://p3.ssl.qhimg.com/d/inn/8a3779be2486/upload_screenshot_1772675658.png)
-> 所有操作也可通过独立命令执行，详见下方「命令一览」。
+> All operations can also be executed via standalone commands — see "Command Reference" below.
-## 命令一览
+## Command Reference
-> 除 `config`、`alias`、`projects`、`completion` 外，其余命令需在**主 worktree 的仓库根目录**下执行。`-b` 参数支持模糊匹配。大部分操作命令（`run`、`create`、`validate`、`merge` 等）需要先执行 `clawt init`。
+> Except for `config`, `alias`, `projects`, and `completion`, all other commands must be run in the **root directory of the main worktree**. The `-b` parameter supports fuzzy matching. Most action commands (`run`, `create`, `validate`, `merge`, etc.) require running `clawt init` first.
-### `clawt init` — 初始化项目级配置
+### `clawt init` — Initialize project-level configuration
 ```bash
-clawt init                # 以当前分支作为主工作分支进行初始化
-clawt init -b <branch>    # 指定主工作分支名
-clawt init show           # 交互式查看和修改项目配置
-clawt init show --json    # 以 JSON 格式输出项目配置
+clawt init                # Initialize with the current branch as the main work branch
+clawt init -b <branch>    # Specify the main work branch name
+clawt init show           # Interactively view and modify project configuration
+clawt init show --json    # Output project configuration in JSON format
 ```
-设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令、worktree 创建后自动执行的 postCreate hook 命令等）。`init show --json` 可以直接输出当前项目配置的 JSON 格式。
+Sets the project's main work branch. Re-running updates the main work branch configuration. `init show` provides an interactive panel for viewing and modifying project settings (e.g., commands to auto-run after validate succeeds, postCreate hook commands after worktree creation, etc.). `init show --json` outputs the current project configuration in JSON format.
-### `clawt run` — 创建 worktree 并执行任务
+### `clawt run` — Create worktree and execute tasks
 ```bash
-# 单 worktree，打开 Claude Code 交互式界面（最常用）
+# Single worktree, opens Claude Code interactive interface (most common)
 clawt run -b <branch>
-# 多任务并行（每个 --tasks 对应一个独立 worktree）
-clawt run -b <branch> --tasks "任务1" --tasks "任务2"
+# Parallel tasks (each --tasks corresponds to an independent worktree)
+clawt run -b <branch> --tasks "task1" --tasks "task2"
-# 从任务文件读取任务列表（使用文件中定义的分支名）
+# Read task list from a task file (uses branch names defined in the file)
 clawt run -f tasks.md
-# 从任务文件读取任务，但用 -b 自动编号分支（文件中分支名可省略）
+# Read tasks from file, but auto-number branches with -b (branch names in file are optional)
 clawt run -f tasks.md -b feat
-# 试运行：仅预览将要创建的 worktree 和任务，不实际执行
-clawt run -b <branch> --tasks "任务1" --tasks "任务2" --dry-run
+# Dry run: preview worktrees and tasks to be created without actually executing
+clawt run -b <branch> --tasks "task1" --tasks "task2" --dry-run
-# 跳过 postCreate hook
+# Skip postCreate hook
 clawt run -b <branch> --no-post-create
 ```
-**`--dry-run` 预览示例：**
+**`--dry-run` preview example:**
 ```
 ════════════════════════════════════════
-  Dry Run 预览
+  Dry Run Preview
 ════════════════════════════════════════
-任务数: 2 │ 并发数: 不限制 │ Worktree: ~/.clawt/worktrees/project
+Tasks: 2 │ Concurrency: unlimited │ Worktree: ~/.clawt/worktrees/project
 ────────────────────────────────────────
 ✓ [1/2] feat-1
-  路径: ~/.clawt/worktrees/project/feat-1
-  任务: 任务1
+  Path: ~/.clawt/worktrees/project/feat-1
+  Task: task1
 ✓ [2/2] feat-2
-  路径: ~/.clawt/worktrees/project/feat-2
-  任务: 任务2
+  Path: ~/.clawt/worktrees/project/feat-2
+  Task: task2
 ════════════════════════════════════════
-✓ 预览完成，无冲突。移除 --dry-run 即可正式执行。
+✓ Preview complete, no conflicts. Remove --dry-run to execute.
 ```
-**任务文件格式：**
+**Task file format:**
 ```markdown
 <!-- CLAWT-TASKS:START -->
 # branch: feat-login
-实现用户登录功能
+Implement user login feature
 <!-- CLAWT-TASKS:END -->
 <!-- CLAWT-TASKS:START -->
 # branch: fix-bug
-修复内存泄漏问题
-支持多行任务描述
+Fix memory leak issue
+Supports multi-line task descriptions
 <!-- CLAWT-TASKS:END -->
 ```
-> 使用 `-b` 时，文件中的 `# branch: ...` 行可省略，分支名由 `-b` 值自动编号（如 `feat-1`、`feat-2`）。
+> When using `-b`, the `# branch: ...` line in the file can be omitted. Branch names are auto-numbered from the `-b` value (e.g., `feat-1`, `feat-2`).
-按 `Ctrl+C` 可中断所有任务。
+Press `Ctrl+C` to interrupt all tasks.
-### `clawt resume` — 恢复之前的 Claude Code 会话
+### `clawt resume` — Resume a previous Claude Code session
 ```bash
-clawt resume -b <branch>   # 指定分支
-clawt resume                # 交互式多选（按创建日期分组）
+clawt resume -b <branch>   # Specify branch
+clawt resume                # Interactive multi-select (grouped by creation date)
-# 非交互式追问
-clawt resume -b <branch> --prompt "追问内容"
-clawt resume -f tasks.md    # 从任务文件批量追问
-clawt resume -f tasks.md -c 2  # 限制并发数
+# Non-interactive follow-up
+clawt resume -b <branch> --prompt "follow-up content"
+clawt resume -f tasks.md    # Batch follow-up from task file
+clawt resume -f tasks.md -c 2  # Limit concurrency
 ```
-不传 `-b` 时，分支列表按创建日期分组显示，支持全局全选和按组全选。选 1 个默认在新终端 Tab 中恢复（设置 `resumeInPlace: true` 可改为在当前终端就地恢复），选多个自动在独立终端 Tab 中批量恢复（仅 macOS）。
+Without `-b`, the branch list is displayed grouped by creation date, supporting global select-all and per-group select-all. Selecting 1 branch resumes in a new terminal tab by default (set `resumeInPlace: true` to resume in the current terminal). Selecting multiple branches automatically resumes in separate terminal tabs in batch (macOS only).
-`--prompt` 用于对指定分支进行非交互式追问，`-f` 从任务文件批量追问多个分支（通过 branch 名匹配已有 worktree）。两者互斥。
+`--prompt` is for non-interactive follow-up on a specified branch. `-f` performs batch follow-up on multiple branches from a task file (matching existing worktrees by branch name). The two are mutually exclusive.
-如果目标 worktree 存在历史会话，会自动继续上次对话（`--continue`）。
+If the target worktree has a previous session, it automatically continues the last conversation (`--continue`).
-> **注意：** 使用 Terminal.app 批量恢复时，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 无需额外授权。终端类型可通过配置项 `terminalApp` 指定。
+> **Note:** When batch resuming with Terminal.app, you need to grant accessibility permissions in "System Settings → Privacy & Security → Accessibility". iTerm2 requires no additional permissions. The terminal type can be configured via the `terminalApp` setting.
-### `clawt create` — 仅创建 worktree（不执行任务）
+### `clawt create` — Create worktree only (without executing tasks)
 ```bash
-clawt create -b <branch>           # 创建 1 个
-clawt create -b <branch> -n 3      # 批量创建 3 个
-clawt create -b <branch> --no-post-create  # 跳过 postCreate hook
+clawt create -b <branch>           # Create 1 worktree
+clawt create -b <branch> -n 3      # Batch create 3 worktrees
+clawt create -b <branch> --no-post-create  # Skip postCreate hook
 ```
-### `clawt validate` — 在主 worktree 中验证分支变更
+### `clawt validate` — Validate branch changes in the main worktree
 ```bash
-clawt validate -b <branch>                    # 将变更迁移到主 worktree 测试
-clawt validate -b <branch> --clean             # 清理 validate 状态
-clawt validate -b <branch> -r "npm test"       # validate 成功后自动运行测试
-clawt validate -b <branch> -r "npm run build"  # validate 成功后自动构建
-clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命令
+clawt validate -b <branch>                    # Migrate changes to main worktree for testing
+clawt validate -b <branch> --clean             # Clean up validate state
+clawt validate -b <branch> -r "npm test"       # Auto-run tests after successful validation
+clawt validate -b <branch> -r "npm run build"  # Auto-build after successful validation
+clawt validate -b <branch> -r "pnpm test & pnpm build"  # Run multiple commands in parallel
 ```
-支持增量模式：再次 validate 同一分支时，可通过 `git diff` 查看两次之间的增量差异。
+Supports incremental mode: when re-validating the same branch, you can view incremental diffs between validations via `git diff`.
-当 patch apply 失败（目标分支与主分支差异过大）时，会自动询问是否执行 `sync` 同步主分支到目标 worktree，无需手动操作。
+When patch apply fails (target branch diverges too much from main), it automatically prompts whether to run `sync` to synchronize the main branch to the target worktree — no manual action needed.
-`-r, --run` 选项可在 validate 成功后自动在主 worktree 中执行指定命令（如测试、构建等），命令执行失败不影响 validate 结果。不传 `-r` 时会自动从项目配置的 `validateRunCommand` 读取（可通过 `clawt init show` 设置）。支持用 `&` 分隔多个命令并行执行：
+The `-r, --run` option auto-executes a specified command in the main worktree after successful validation (e.g., tests, builds). Command failure does not affect the validation result. Without `-r`, it automatically reads from the project's `validateRunCommand` config (configurable via `clawt init show`). Use `&` to separate multiple commands for parallel execution:
-| 用法 | 行为 |
+| Usage | Behavior |
 | ---- | ---- |
-| `-r "npm test"` | 单命令，同步执行 |
-| `-r "npm lint && npm test"` | `&&` 不拆分，同步执行 |
-| `-r "pnpm test & pnpm build"` | 并行执行，等全部完成后汇总结果 |
+| `-r "npm test"` | Single command, synchronous |
+| `-r "npm lint && npm test"` | `&&` is not split, synchronous |
+| `-r "pnpm test & pnpm build"` | Parallel execution, waits for all to complete |
-### `clawt cover` — 将验证分支修改覆盖回目标 worktree
+### `clawt cover` — Cover validated branch changes back to target worktree
 ```bash
-clawt cover    # 在验证分支上执行，自动推导目标分支
+clawt cover    # Execute on the validate branch, auto-deduces target branch
 ```
-在 validate 验证过程中，如果在主 worktree（验证分支上）修改了代码，可通过 `cover` 将修改覆盖回目标 worktree。当工作区无修改时会提示确认，避免误操作。
+During validation, if you modified code on the main worktree (on the validate branch), use `cover` to push those changes back to the target worktree. When there are no working directory changes, it prompts for confirmation to avoid accidental operations.
-### `clawt sync` — 同步主分支代码到目标 worktree
+### `clawt sync` — Sync main branch code to target worktree
 ```bash
 clawt sync -b <branch>
 ```
-当 `validate` 的 patch apply 失败时也会自动提示执行 sync，通常无需手动调用。
+Also automatically prompted when `validate` patch apply fails — usually no manual invocation needed.
-### `clawt merge` — 合并分支到主 worktree
+### `clawt merge` — Merge branch into main worktree
 ```bash
-clawt merge -b <branch> -m "feat: 提交信息"   # 通过 -m 直接指定提交信息
-clawt merge -b <branch>                        # 交互模式下有未提交修改时会询问输入提交信息
-clawt merge -b <branch> --auto                 # 遇到冲突直接调用 AI 解决
+clawt merge -b <branch> -m "feat: commit message"   # Specify commit message via -m
+clawt merge -b <branch>                               # In interactive mode, prompts for commit message if there are uncommitted changes
+clawt merge -b <branch> --auto                        # Resolve conflicts with AI automatically
 ```
-交互模式下，如果目标 worktree 有未提交修改或 squash 后需要提交，会自动询问输入提交信息，无需提前指定 `-m`。非交互模式（`-y` / CI）下未提供 `-m` 时会提示退出。
+In interactive mode, if the target worktree has uncommitted changes or a commit message is needed after squash, it automatically prompts for input — no need to specify `-m` in advance. In non-interactive mode (`-y` / CI), it exits with an error if `-m` is not provided.
-### `clawt remove` — 移除 worktree
+### `clawt remove` — Remove worktree
 ```bash
-clawt remove -b <branch>    # 移除指定分支的 worktree（支持模糊匹配）
-clawt remove                 # 交互式多选要移除的 worktree
-clawt remove --all           # 移除当前项目下所有 worktree
+clawt remove -b <branch>    # Remove worktree for specified branch (supports fuzzy matching)
+clawt remove                 # Interactive multi-select worktrees to remove (grouped by creation date)
+clawt remove --all           # Remove all worktrees for the current project
 ```
-### `clawt list` — 列出所有 worktree
+### `clawt list` — List all worktrees
 ```bash
-clawt list            # 文本格式
-clawt list --json     # JSON 格式
+clawt list            # Text format
+clawt list --json     # JSON format
 ```
-### `clawt status` — 项目状态总览
+### `clawt status` — Project status overview
 ```bash
-clawt status          # 文本格式
-clawt status --json   # JSON 格式
-clawt status -i       # 交互式面板模式（实时刷新，支持键盘导航和快捷操作）
+clawt status          # Text format
+clawt status --json   # JSON format
+clawt status -i       # Interactive panel mode (real-time refresh, keyboard navigation and shortcuts)
 ```
-展示主 worktree 状态、各 worktree 的变更详情（含分支创建时间和验证状态）以及 validate 快照摘要。
+Displays the main worktree status, change details for each worktree (including branch creation time and validation status), and validate snapshot summaries.
-交互式面板模式（`-i`）提供实时刷新的 TUI 界面，支持方向键导航选中 worktree，并通过快捷键直接执行 validate / merge / remove / resume / sync 等操作：
+Interactive panel mode (`-i`) provides a real-time TUI interface with arrow key navigation and shortcut-driven operations:
-| 快捷键 | 操作 |
+| Shortcut | Action |
 | ------ | ---- |
-| `↑` `↓` | 导航选中 worktree |
-| `v` `m` `d` `r` `s` `c` | 验证 / 合并 / 删除 / 恢复 / 同步 / 覆盖 |
-| `f` | 手动刷新 |
-| `q` / `Ctrl+C` | 退出 |
+| `↑` `↓` | Navigate and select worktree |
+| `v` `m` `d` `r` `s` `c` | Validate / Merge / Delete / Resume / Sync / Cover |
+| `f` | Manual refresh |
+| `q` / `Ctrl+C` | Quit |
-### `clawt reset` — 重置主 worktree 到干净状态
+### `clawt reset` — Reset main worktree to clean state
 ```bash
 clawt reset
 ```
-### `clawt home` — 切换回主工作分支
+### `clawt home` — Switch back to main work branch
 ```bash
 clawt home
 ```
-如果当前已在主工作分支上，会提示无需切换。
+If already on the main work branch, a message indicates no switch is needed.
-### `clawt tasks` — 任务文件管理
+### `clawt tasks` — Task file management
 ```bash
-clawt tasks init             # 生成任务模板文件（默认输出到 .clawt/tasks/ 目录）
-clawt tasks init [path]      # 指定输出路径
+clawt tasks init             # Generate task template file (defaults to .clawt/tasks/ directory)
+clawt tasks init [path]      # Specify output path
 ```
-快速生成 `clawt run -f` 所需的任务文件模板，包含格式说明注释和示例任务块。
+Quickly generates the task file template needed by `clawt run -f`, including format instructions and example task blocks.
-### `clawt projects` — 跨项目 worktree 概览
+### `clawt projects` — Cross-project worktree overview
 ```bash
-clawt projects             # 查看所有项目概览
-clawt projects my-project  # 查看指定项目的 worktree 详情
-clawt projects --json      # JSON 格式输出
+clawt projects             # View all projects overview
+clawt projects my-project  # View worktree details for a specific project
+clawt projects --json      # JSON format output
 ```
-展示所有项目的 worktree 数量、磁盘占用和最近活跃时间，或查看指定项目下每个 worktree 的详细信息。
+Displays worktree counts, disk usage, and last active time for all projects, or detailed information for each worktree under a specific project.
-### `clawt config` — 交互式查看和修改配置
+### `clawt config` — Interactively view and modify configuration
 ```bash
-clawt config                          # 交互式修改配置（选择配置项并修改值）
-clawt config set <key> <value>        # 直接设置某个配置项
-clawt config get <key>                # 获取某个配置项的值
-clawt config reset                    # 恢复默认配置
+clawt config                          # Interactive modification (select config items and modify values)
+clawt config set <key> <value>        # Directly set a config item
+clawt config get <key>                # Get a config item's value
+clawt config reset                    # Restore default configuration
 ```
-**使用示例：**
+**Usage examples:**
 ```bash
-# 交互式修改（列出所有配置项，方向键选择，根据类型自动提示）
+# Interactive modification (lists all config items, arrow key selection, auto-prompts by type)
 clawt config
-# 直接设置
+# Direct setting
 clawt config set autoDeleteBranch true
 clawt config set maxConcurrency 4
 clawt config set terminalApp iterm2
-# 查看某项配置
+# View a config item
 clawt config get maxConcurrency
 ```
-### `clawt completion` — Shell 自动补全
+### `clawt completion` — Shell auto-completion
-为终端提供命令、子命令、选项，甚至分支名和配置项的自动补全功能。
+Provides auto-completion for commands, subcommands, options, and even branch names and config keys in the terminal.
 ```bash
-# 自动安装补全脚本（推荐）
+# Auto-install completion script (recommended)
 clawt completion install
-# 或手动将脚本添加到你的 shell 配置文件
+# Or manually add the script to your shell config file
 clawt completion bash >> ~/.bashrc
 clawt completion zsh >> ~/.zshrc
 ```
-> **支持特性：** 所有子命令、选项、`-b` 参数自动补全本地 `worktree` 分支名、`-f` 参数自动补全文件路径，以及 `config set/get` 键名自动补全。
+> **Supported features:** All subcommands, options, `-b` parameter auto-completes local worktree branch names, `-f` parameter auto-completes file paths, and `config set/get` key name auto-completion.
-### `clawt alias` — 管理命令别名
+### `clawt alias` — Manage command aliases
 ```bash
-clawt alias                          # 列出所有命令别名
-clawt alias list                     # 列出所有命令别名
-clawt alias set <alias> <command>    # 设置命令别名
-clawt alias remove <alias>           # 移除命令别名
+clawt alias                          # List all command aliases
+clawt alias list                     # List all command aliases
+clawt alias set <alias> <command>    # Set a command alias
+clawt alias remove <alias>           # Remove a command alias
 ```
-**使用示例：**
+**Usage examples:**
 ```bash
-# 设置别名
+# Set aliases
 clawt alias set l list
 clawt alias set r run
 clawt alias set v validate
-# 使用别名（等同于对应的完整命令）
-clawt l          # 等同于 clawt list
-clawt r task.md  # 等同于 clawt run task.md
+# Use aliases (equivalent to the corresponding full commands)
+clawt l          # Equivalent to clawt list
+clawt r task.md  # Equivalent to clawt run task.md
-# 移除别名
+# Remove alias
 clawt alias remove l
 ```
-> **约束：** 别名不能覆盖内置命令名，目标必须是已注册的内置命令。别名的选项和参数会完全透传给目标命令。
+> **Constraints:** Aliases cannot override built-in command names, and targets must be registered built-in commands. Options and arguments of aliases are fully passed through to the target command.
-## 配置
+## Configuration
-配置文件位于 `~/.clawt/config.json`，安装后自动生成：
+Configuration file is located at `~/.clawt/config.json`, auto-generated after installation:
-| 配置项 | 默认值 | 说明 |
+| Config Item | Default | Description |
 | ------ | ------ | ---- |
-| `autoDeleteBranch` | `false` | 自动删除已合并/已移除的分支 |
-| `claudeCodeCommand` | `"claude"` | Claude Code CLI 启动命令 |
-| `autoPullPush` | `false` | merge 后自动 pull/push |
-| `confirmDestructiveOps` | `true` | 破坏性操作前确认 |
-| `maxConcurrency` | `0` | run 命令最大并发数，`0` 为不限制 |
-| `terminalApp` | `"auto"` | 批量 resume 使用的终端：`auto` / `iterm2` / `terminal` |
-| `resumeInPlace` | `false` | resume 单选时在当前终端就地恢复，`false` 则在新 Tab 中打开 |
-| `aliases` | `{}` | 命令别名映射（如 `{"l": "list", "r": "run"}`） |
-| `autoUpdate` | `true` | 自动检查新版本（每 24 小时检查一次 npm registry） |
-| `conflictResolveMode` | `"ask"` | merge 冲突时的解决模式：`ask`（询问是否使用 AI）、`auto`（自动 AI 解决）、`manual`（手动解决） |
-| `conflictResolveTimeoutMs` | `600000` | Claude Code 冲突解决超时时间（毫秒），默认 10 分钟 |
+| `autoDeleteBranch` | `false` | Auto-delete merged/removed branches |
+| `claudeCodeCommand` | `"claude"` | Claude Code CLI launch command |
+| `autoPullPush` | `false` | Auto pull/push after merge |
+| `confirmDestructiveOps` | `true` | Confirm before destructive operations |
+| `maxConcurrency` | `0` | Max concurrency for run command, `0` means unlimited |
+| `terminalApp` | `"auto"` | Terminal for batch resume: `auto` / `iterm2` / `terminal` |
+| `resumeInPlace` | `false` | Resume single selection in current terminal; `false` opens in new tab |
+| `aliases` | `{}` | Command alias mapping (e.g., `{"l": "list", "r": "run"}`) |
+| `autoUpdate` | `true` | Auto-check for new versions (checks npm registry every 24 hours) |
+| `conflictResolveMode` | `"ask"` | Merge conflict resolution mode: `ask` (prompt for AI), `auto` (auto AI resolve), `manual` (manual resolve) |
+| `conflictResolveTimeoutMs` | `600000` | Claude Code conflict resolution timeout (ms), default 10 minutes |
 ## postCreate Hook
-worktree 创建后可自动执行任意初始化命令（如安装依赖、生成配置文件、编译资源等），`create` 和 `run` 命令均支持。
+Automatically execute any initialization commands after worktree creation (e.g., install dependencies, generate config files, compile resources, etc.). Supported by both `create` and `run` commands.
-**配置方式（二选一）：**
+**Configuration (choose one):**
-1. **项目配置**：通过 `clawt init show` 设置 `postCreate` 字段（如 `npm install`）
-2. **脚本文件**：在项目根目录创建 `.clawt/postCreate.sh` 并赋予执行权限
+1. **Project config**: Set the `postCreate` field via `clawt init show` (e.g., `npm install`)
+2. **Script file**: Create `.clawt/postCreate.sh` in the project root and grant execute permission
-项目配置优先于脚本文件。使用 `--no-post-create` 可跳过 hook 执行。
+Project config takes priority over the script file. Use `--no-post-create` to skip hook execution.
-hook 以 fire-and-forget 模式后台异步并行执行，不阻塞主流程。执行结果仅写入日志。
+Hooks run asynchronously in the background (fire-and-forget), not blocking the main flow. Results are only logged.
-## 全局选项
+## Global Options
-| 选项 | 说明 |
+| Option | Description |
 | ---- | ---- |
-| `--debug` | 输出调试信息 |
-| `-y, --yes` | 跳过所有交互式确认，适用于脚本/CI 环境 |
+| `--debug` | Output debug information |
+| `-y, --yes` | Skip all interactive confirmations, suitable for scripts/CI environments |
-## 环境变量
+## Environment Variables
-| 环境变量 | 说明 |
+| Variable | Description |
 | -------- | ---- |
-| `CI` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
-| `CLAWT_NON_INTERACTIVE` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
+| `CI` | When set to `true` or `1`, enables non-interactive mode (equivalent to `--yes`) |
+| `CLAWT_NON_INTERACTIVE` | When set to `true` or `1`, enables non-interactive mode (equivalent to `--yes`) |
-> **优先级：** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > 默认交互模式
+> **Priority:** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > default interactive mode
-## 日志
+## Logs
-日志保存在 `~/.clawt/logs/`，按日期滚动，保留 30 天。
+Logs are saved in `~/.clawt/logs/`, rotated by date, retained for 30 days.

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,379 @@
+# Clawt
+[English](./README.md) | **[中文](./README.zh-CN.md)**
+基于 Git Worktree 并行执行多个 Claude Code Agent 任务，所有 Agent 的代码修改互不干扰。
+## 安装
+```bash
+npm i -g clawt
+```
+**环境要求：** Node.js >= 18 · Git >= 2.15 · Claude Code CLI
+## 快速开始
+```bash
+# 1. 在项目根目录（包含 .git 的目录）下初始化，确认主工作分支
+clawt init
+# 2. 并行执行任务，每个任务在独立的 worktree 中运行
+clawt run -b feat-login
+clawt run -b feat-search
+clawt run -b fix-bug
+# 3. 打开交互式面板，实时查看所有任务状态，一站式完成后续操作
+clawt status -i
+```
+`clawt status -i` 提供实时刷新的 TUI 面板，用方向键选中 worktree 后可直接按快捷键操作：
+| 快捷键 | 操作 | 等同命令 |
+| ------ | ---- | -------- |
+| `v` | 验证分支变更 | `clawt validate -b <branch>` |
+| `m` | 合并到主分支 | `clawt merge -b <branch>` |
+| `r` | 恢复 Claude Code 会话 | `clawt resume -b <branch>` |
+| `s` | 同步主分支代码 | `clawt sync -b <branch>` |
+| `d` | 删除 worktree | `clawt remove -b <branch>` |
+| `c` | 覆盖修改回目标 worktree | `clawt cover` |
+| `q` | 退出面板 | — |
+示例：
+![](https://p3.ssl.qhimg.com/d/inn/8a3779be2486/upload_screenshot_1772675658.png)
+> 所有操作也可通过独立命令执行，详见下方「命令一览」。
+## 命令一览
+> 除 `config`、`alias`、`projects`、`completion` 外，其余命令需在**主 worktree 的仓库根目录**下执行。`-b` 参数支持模糊匹配。大部分操作命令（`run`、`create`、`validate`、`merge` 等）需要先执行 `clawt init`。
+### `clawt init` — 初始化项目级配置
+```bash
+clawt init                # 以当前分支作为主工作分支进行初始化
+clawt init -b <branch>    # 指定主工作分支名
+clawt init show           # 交互式查看和修改项目配置
+clawt init show --json    # 以 JSON 格式输出项目配置
+```
+设置项目的主工作分支。重复执行会更新主工作分支配置。`init show` 提供交互式面板，可查看和修改项目配置项（如 validate 成功后自动执行的命令、worktree 创建后自动执行的 postCreate hook 命令等）。`init show --json` 可以直接输出当前项目配置的 JSON 格式。
+### `clawt run` — 创建 worktree 并执行任务
+```bash
+# 单 worktree，打开 Claude Code 交互式界面（最常用）
+clawt run -b <branch>
+# 多任务并行（每个 --tasks 对应一个独立 worktree）
+clawt run -b <branch> --tasks "任务1" --tasks "任务2"
+# 从任务文件读取任务列表（使用文件中定义的分支名）
+clawt run -f tasks.md
+# 从任务文件读取任务，但用 -b 自动编号分支（文件中分支名可省略）
+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` 预览示例：**
+```
+════════════════════════════════════════
+  Dry Run 预览
+════════════════════════════════════════
+任务数: 2 │ 并发数: 不限制 │ Worktree: ~/.clawt/worktrees/project
+────────────────────────────────────────
+✓ [1/2] feat-1
+  路径: ~/.clawt/worktrees/project/feat-1
+  任务: 任务1
+✓ [2/2] feat-2
+  路径: ~/.clawt/worktrees/project/feat-2
+  任务: 任务2
+════════════════════════════════════════
+✓ 预览完成，无冲突。移除 --dry-run 即可正式执行。
+```
+**任务文件格式：**
+```markdown
+<!-- CLAWT-TASKS:START -->
+# branch: feat-login
+实现用户登录功能
+<!-- CLAWT-TASKS:END -->
+<!-- CLAWT-TASKS:START -->
+# branch: fix-bug
+修复内存泄漏问题
+支持多行任务描述
+<!-- CLAWT-TASKS:END -->
+```
+> 使用 `-b` 时，文件中的 `# branch: ...` 行可省略，分支名由 `-b` 值自动编号（如 `feat-1`、`feat-2`）。
+按 `Ctrl+C` 可中断所有任务。
+### `clawt resume` — 恢复之前的 Claude Code 会话
+```bash
+clawt resume -b <branch>   # 指定分支
+clawt resume                # 交互式多选（按创建日期分组）
+# 非交互式追问
+clawt resume -b <branch> --prompt "追问内容"
+clawt resume -f tasks.md    # 从任务文件批量追问
+clawt resume -f tasks.md -c 2  # 限制并发数
+```
+不传 `-b` 时，分支列表按创建日期分组显示，支持全局全选和按组全选。选 1 个默认在新终端 Tab 中恢复（设置 `resumeInPlace: true` 可改为在当前终端就地恢复），选多个自动在独立终端 Tab 中批量恢复（仅 macOS）。
+`--prompt` 用于对指定分支进行非交互式追问，`-f` 从任务文件批量追问多个分支（通过 branch 名匹配已有 worktree）。两者互斥。
+如果目标 worktree 存在历史会话，会自动继续上次对话（`--continue`）。
+> **注意：** 使用 Terminal.app 批量恢复时，需要在「系统设置 → 隐私与安全性 → 辅助功能」中授权终端应用。iTerm2 无需额外授权。终端类型可通过配置项 `terminalApp` 指定。
+### `clawt create` — 仅创建 worktree（不执行任务）
+```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 中验证分支变更
+```bash
+clawt validate -b <branch>                    # 将变更迁移到主 worktree 测试
+clawt validate -b <branch> --clean             # 清理 validate 状态
+clawt validate -b <branch> -r "npm test"       # validate 成功后自动运行测试
+clawt validate -b <branch> -r "npm run build"  # validate 成功后自动构建
+clawt validate -b <branch> -r "pnpm test & pnpm build"  # 并行执行多个命令
+```
+支持增量模式：再次 validate 同一分支时，可通过 `git diff` 查看两次之间的增量差异。
+当 patch apply 失败（目标分支与主分支差异过大）时，会自动询问是否执行 `sync` 同步主分支到目标 worktree，无需手动操作。
+`-r, --run` 选项可在 validate 成功后自动在主 worktree 中执行指定命令（如测试、构建等），命令执行失败不影响 validate 结果。不传 `-r` 时会自动从项目配置的 `validateRunCommand` 读取（可通过 `clawt init show` 设置）。支持用 `&` 分隔多个命令并行执行：
+| 用法 | 行为 |
+| ---- | ---- |
+| `-r "npm test"` | 单命令，同步执行 |
+| `-r "npm lint && npm test"` | `&&` 不拆分，同步执行 |
+| `-r "pnpm test & pnpm build"` | 并行执行，等全部完成后汇总结果 |
+### `clawt cover` — 将验证分支修改覆盖回目标 worktree
+```bash
+clawt cover    # 在验证分支上执行，自动推导目标分支
+```
+在 validate 验证过程中，如果在主 worktree（验证分支上）修改了代码，可通过 `cover` 将修改覆盖回目标 worktree。当工作区无修改时会提示确认，避免误操作。
+### `clawt sync` — 同步主分支代码到目标 worktree
+```bash
+clawt sync -b <branch>
+```
+当 `validate` 的 patch apply 失败时也会自动提示执行 sync，通常无需手动调用。
+### `clawt merge` — 合并分支到主 worktree
+```bash
+clawt merge -b <branch> -m "feat: 提交信息"   # 通过 -m 直接指定提交信息
+clawt merge -b <branch>                        # 交互模式下有未提交修改时会询问输入提交信息
+clawt merge -b <branch> --auto                 # 遇到冲突直接调用 AI 解决
+```
+交互模式下，如果目标 worktree 有未提交修改或 squash 后需要提交，会自动询问输入提交信息，无需提前指定 `-m`。非交互模式（`-y` / CI）下未提供 `-m` 时会提示退出。
+### `clawt remove` — 移除 worktree
+```bash
+clawt remove -b <branch>    # 移除指定分支的 worktree（支持模糊匹配）
+clawt remove                 # 交互式多选要移除的 worktree（按创建日期分组）
+clawt remove --all           # 移除当前项目下所有 worktree
+```
+### `clawt list` — 列出所有 worktree
+```bash
+clawt list            # 文本格式
+clawt list --json     # JSON 格式
+```
+### `clawt status` — 项目状态总览
+```bash
+clawt status          # 文本格式
+clawt status --json   # JSON 格式
+clawt status -i       # 交互式面板模式（实时刷新，支持键盘导航和快捷操作）
+```
+展示主 worktree 状态、各 worktree 的变更详情（含分支创建时间和验证状态）以及 validate 快照摘要。
+交互式面板模式（`-i`）提供实时刷新的 TUI 界面，支持方向键导航选中 worktree，并通过快捷键直接执行 validate / merge / remove / resume / sync 等操作：
+| 快捷键 | 操作 |
+| ------ | ---- |
+| `↑` `↓` | 导航选中 worktree |
+| `v` `m` `d` `r` `s` `c` | 验证 / 合并 / 删除 / 恢复 / 同步 / 覆盖 |
+| `f` | 手动刷新 |
+| `q` / `Ctrl+C` | 退出 |
+### `clawt reset` — 重置主 worktree 到干净状态
+```bash
+clawt reset
+```
+### `clawt home` — 切换回主工作分支
+```bash
+clawt home
+```
+如果当前已在主工作分支上，会提示无需切换。
+### `clawt tasks` — 任务文件管理
+```bash
+clawt tasks init             # 生成任务模板文件（默认输出到 .clawt/tasks/ 目录）
+clawt tasks init [path]      # 指定输出路径
+```
+快速生成 `clawt run -f` 所需的任务文件模板，包含格式说明注释和示例任务块。
+### `clawt projects` — 跨项目 worktree 概览
+```bash
+clawt projects             # 查看所有项目概览
+clawt projects my-project  # 查看指定项目的 worktree 详情
+clawt projects --json      # JSON 格式输出
+```
+展示所有项目的 worktree 数量、磁盘占用和最近活跃时间，或查看指定项目下每个 worktree 的详细信息。
+### `clawt config` — 交互式查看和修改配置
+```bash
+clawt config                          # 交互式修改配置（选择配置项并修改值）
+clawt config set <key> <value>        # 直接设置某个配置项
+clawt config get <key>                # 获取某个配置项的值
+clawt config reset                    # 恢复默认配置
+```
+**使用示例：**
+```bash
+# 交互式修改（列出所有配置项，方向键选择，根据类型自动提示）
+clawt config
+# 直接设置
+clawt config set autoDeleteBranch true
+clawt config set maxConcurrency 4
+clawt config set terminalApp iterm2
+# 查看某项配置
+clawt config get maxConcurrency
+```
+### `clawt completion` — Shell 自动补全
+为终端提供命令、子命令、选项，甚至分支名和配置项的自动补全功能。
+```bash
+# 自动安装补全脚本（推荐）
+clawt completion install
+# 或手动将脚本添加到你的 shell 配置文件
+clawt completion bash >> ~/.bashrc
+clawt completion zsh >> ~/.zshrc
+```
+> **支持特性：** 所有子命令、选项、`-b` 参数自动补全本地 `worktree` 分支名、`-f` 参数自动补全文件路径，以及 `config set/get` 键名自动补全。
+### `clawt alias` — 管理命令别名
+```bash
+clawt alias                          # 列出所有命令别名
+clawt alias list                     # 列出所有命令别名
+clawt alias set <alias> <command>    # 设置命令别名
+clawt alias remove <alias>           # 移除命令别名
+```
+**使用示例：**
+```bash
+# 设置别名
+clawt alias set l list
+clawt alias set r run
+clawt alias set v validate
+# 使用别名（等同于对应的完整命令）
+clawt l          # 等同于 clawt list
+clawt r task.md  # 等同于 clawt run task.md
+# 移除别名
+clawt alias remove l
+```
+> **约束：** 别名不能覆盖内置命令名，目标必须是已注册的内置命令。别名的选项和参数会完全透传给目标命令。
+## 配置
+配置文件位于 `~/.clawt/config.json`，安装后自动生成：
+| 配置项 | 默认值 | 说明 |
+| ------ | ------ | ---- |
+| `autoDeleteBranch` | `false` | 自动删除已合并/已移除的分支 |
+| `claudeCodeCommand` | `"claude"` | Claude Code CLI 启动命令 |
+| `autoPullPush` | `false` | merge 后自动 pull/push |
+| `confirmDestructiveOps` | `true` | 破坏性操作前确认 |
+| `maxConcurrency` | `0` | run 命令最大并发数，`0` 为不限制 |
+| `terminalApp` | `"auto"` | 批量 resume 使用的终端：`auto` / `iterm2` / `terminal` |
+| `resumeInPlace` | `false` | resume 单选时在当前终端就地恢复，`false` 则在新 Tab 中打开 |
+| `aliases` | `{}` | 命令别名映射（如 `{"l": "list", "r": "run"}`） |
+| `autoUpdate` | `true` | 自动检查新版本（每 24 小时检查一次 npm registry） |
+| `conflictResolveMode` | `"ask"` | merge 冲突时的解决模式：`ask`（询问是否使用 AI）、`auto`（自动 AI 解决）、`manual`（手动解决） |
+| `conflictResolveTimeoutMs` | `600000` | Claude Code 冲突解决超时时间（毫秒），默认 10 分钟 |
+## postCreate Hook
+worktree 创建后可自动执行任意初始化命令（如安装依赖、生成配置文件、编译资源等），`create` 和 `run` 命令均支持。
+**配置方式（二选一）：**
+1. **项目配置**：通过 `clawt init show` 设置 `postCreate` 字段（如 `npm install`）
+2. **脚本文件**：在项目根目录创建 `.clawt/postCreate.sh` 并赋予执行权限
+项目配置优先于脚本文件。使用 `--no-post-create` 可跳过 hook 执行。
+hook 以 fire-and-forget 模式后台异步并行执行，不阻塞主流程。执行结果仅写入日志。
+## 全局选项
+| 选项 | 说明 |
+| ---- | ---- |
+| `--debug` | 输出调试信息 |
+| `-y, --yes` | 跳过所有交互式确认，适用于脚本/CI 环境 |
+## 环境变量
+| 环境变量 | 说明 |
+| -------- | ---- |
+| `CI` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
+| `CLAWT_NON_INTERACTIVE` | 设置为 `true` 或 `1` 时，自动启用非交互模式（等同于 `--yes`） |
+> **优先级：** `--yes` > `CI` > `CLAWT_NON_INTERACTIVE` > 默认交互模式
+## 日志
+日志保存在 `~/.clawt/logs/`，按日期滚动，保留 30 天。

package/dist/index.js CHANGED Viewed

@@ -26,6 +26,8 @@ var VALIDATE_BRANCH_PREFIX = "clawt-validate-";
 var COMMON_MESSAGES = {
   /** 不在主 worktree 根目录 */
   NOT_MAIN_WORKTREE: "\u8BF7\u5728\u4E3B worktree \u7684\u6839\u76EE\u5F55\u4E0B\u6267\u884C clawt",
+  /** 不在 git 仓库中 */
+  NOT_GIT_REPO: "\u5F53\u524D\u76EE\u5F55\u4E0D\u662F git \u4ED3\u5E93\uFF0C\u8BF7\u5148\u6267\u884C git init \u5E76\u63D0\u4EA4\u540E\uFF0C\u518D\u6267\u884C clawt init \u521D\u59CB\u5316\u9879\u76EE",
   /** Git 未安装 */
   GIT_NOT_INSTALLED: "Git \u672A\u5B89\u88C5\u6216\u4E0D\u5728 PATH \u4E2D\uFF0C\u8BF7\u5148\u5B89\u88C5 Git",
   /** Claude Code CLI 未安装 */
@@ -1735,15 +1737,11 @@ async function ensureOnMainWorkBranch(cwd) {
 // src/utils/validation.ts
 function validateMainWorktree() {
-  try {
-    const gitCommonDir = getGitCommonDir();
-    if (gitCommonDir !== ".git") {
-      throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
-    }
-  } catch (error) {
-    if (error instanceof ClawtError) {
-      throw error;
-    }
+  if (!isInsideGitRepo()) {
+    throw new ClawtError(MESSAGES.NOT_GIT_REPO);
+  }
+  const gitCommonDir = getGitCommonDir();
+  if (gitCommonDir !== ".git") {
     throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
   }
 }
@@ -2183,48 +2181,6 @@ async function promptSelectBranch(worktrees, message) {
   }).run();
   return worktrees.find((wt) => wt.branch === selectedBranch);
 }
-async function promptMultiSelectBranches(worktrees, message) {
-  if (isNonInteractive()) {
-    throw new ClawtError("\u975E\u4EA4\u4E92\u6A21\u5F0F\u4E0B\u65E0\u6CD5\u8FDB\u884C\u5206\u652F\u591A\u9009\uFF0C\u8BF7\u901A\u8FC7 -b \u53C2\u6570\u7CBE\u786E\u6307\u5B9A\u5206\u652F\u540D");
-  }
-  const branchChoices = worktrees.map((wt) => ({
-    name: wt.branch,
-    message: wt.branch
-  }));
-  const choices = [
-    { name: SELECT_ALL_NAME, message: SELECT_ALL_LABEL },
-    ...branchChoices
-  ];
-  const MultiSelect = Enquirer3.MultiSelect;
-  class MultiSelectWithSelectAll extends MultiSelect {
-    space() {
-      if (!this.focused) return;
-      if (this.focused.name === SELECT_ALL_NAME) {
-        const willEnable = !this.focused.enabled;
-        for (const ch of this.choices) {
-          ch.enabled = willEnable;
-        }
-        return this.render();
-      }
-      this.toggle(this.focused);
-      const selectAllChoice = this.choices.find((ch) => ch.name === SELECT_ALL_NAME);
-      const branchItems = this.choices.filter((ch) => ch.name !== SELECT_ALL_NAME);
-      if (selectAllChoice) {
-        selectAllChoice.enabled = branchItems.every((ch) => ch.enabled);
-      }
-      return this.render();
-    }
-  }
-  const selectedBranches = await new MultiSelectWithSelectAll({
-    message,
-    choices,
-    // 使用空心圆/实心圆作为选中指示符
-    symbols: {
-      indicator: { on: "\u25CF", off: "\u25CB" }
-    }
-  }).run();
-  return worktrees.filter((wt) => selectedBranches.includes(wt.branch));
-}
 async function promptGroupedMultiSelectBranches(worktrees, message) {
   if (isNonInteractive()) {
     throw new ClawtError("\u975E\u4EA4\u4E92\u6A21\u5F0F\u4E0B\u65E0\u6CD5\u8FDB\u884C\u5206\u652F\u591A\u9009\uFF0C\u8BF7\u901A\u8FC7 -b \u53C2\u6570\u7CBE\u786E\u6307\u5B9A\u5206\u652F\u540D");
@@ -2307,7 +2263,7 @@ async function resolveTargetWorktrees(worktrees, messages, branchName) {
     if (worktrees.length === 1) {
       return [worktrees[0]];
     }
-    return promptMultiSelectBranches(worktrees, messages.selectBranch);
+    return promptGroupedMultiSelectBranches(worktrees, messages.selectBranch);
   }
   const exactMatch = findExactMatch(worktrees, branchName);
   if (exactMatch) {
@@ -2318,7 +2274,7 @@ async function resolveTargetWorktrees(worktrees, messages, branchName) {
     return [fuzzyMatches[0]];
   }
   if (fuzzyMatches.length > 1) {
-    return promptMultiSelectBranches(fuzzyMatches, messages.multipleMatches(branchName));
+    return promptGroupedMultiSelectBranches(fuzzyMatches, messages.multipleMatches(branchName));
   }
   const allBranches = worktrees.map((wt) => wt.branch);
   throw new ClawtError(messages.noMatch(branchName, allBranches));
@@ -6086,7 +6042,7 @@ function registerHomeCommand(program2) {
 }
 async function handleHome() {
   if (!isInsideGitRepo()) {
-    printError(MESSAGES.NOT_MAIN_WORKTREE);
+    printError(MESSAGES.NOT_GIT_REPO);
     return;
   }
   if (!isMainWorktree()) {

package/dist/postinstall.js CHANGED Viewed

@@ -17,6 +17,8 @@ var PROJECTS_CONFIG_DIR = join(CLAWT_HOME, "projects");
 var COMMON_MESSAGES = {
   /** 不在主 worktree 根目录 */
   NOT_MAIN_WORKTREE: "\u8BF7\u5728\u4E3B worktree \u7684\u6839\u76EE\u5F55\u4E0B\u6267\u884C clawt",
+  /** 不在 git 仓库中 */
+  NOT_GIT_REPO: "\u5F53\u524D\u76EE\u5F55\u4E0D\u662F git \u4ED3\u5E93\uFF0C\u8BF7\u5148\u6267\u884C git init \u5E76\u63D0\u4EA4\u540E\uFF0C\u518D\u6267\u884C clawt init \u521D\u59CB\u5316\u9879\u76EE",
   /** Git 未安装 */
   GIT_NOT_INSTALLED: "Git \u672A\u5B89\u88C5\u6216\u4E0D\u5728 PATH \u4E2D\uFF0C\u8BF7\u5148\u5B89\u88C5 Git",
   /** Claude Code CLI 未安装 */

package/docs/remove.md CHANGED Viewed

@@ -35,12 +35,12 @@ clawt remove
      - **未传 `-b` 参数**：
        - 无可用 worktree → 报错退出
        - 仅 1 个 worktree → 直接使用，无需选择
-       - 多个 worktree → 通过交互式多选列表（Enquirer.MultiSelect）让用户选择（空格选择，回车确认）
+       - 多个 worktree → 通过 `promptGroupedMultiSelectBranches` 展示**按日期分组的交互式多选列表**（详见 [resume.md](./resume.md) 中的「按日期分组多选」章节），支持三级联动选择（全局全选 → 组全选 → 单分支）
      - **传了 `-b` 参数**：
        1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
        2. **模糊匹配**（子串匹配，大小写不敏感）：
           - 唯一匹配 → 直接使用
-          - 多个匹配 → 通过交互式多选列表让用户从匹配结果中选择
+          - 多个匹配 → 通过按日期分组的交互式多选列表让用户从匹配结果中选择
        3. **无匹配** → 报错退出，并列出所有可用分支名
 4. **当前分支安全检查**：逐个检查待移除的分支，如果该分支或其对应的验证分支（`clawt-validate-<branchName>`）是主 worktree 当前所在分支，则抛出错误并阻止移除。
 5. 列出即将移除的 worktree 及对应分支：

package/package.json CHANGED Viewed

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

package/src/commands/home.ts CHANGED Viewed

@@ -37,7 +37,7 @@ export function registerHomeCommand(program: Command): void {
 async function handleHome(): Promise<void> {
   // 场景 1：不在 git 仓库中，直接报错
   if (!isInsideGitRepo()) {
-    printError(MESSAGES.NOT_MAIN_WORKTREE);
+    printError(MESSAGES.NOT_GIT_REPO);
     return;
   }

package/src/constants/messages/common.ts CHANGED Viewed

@@ -2,6 +2,8 @@
 export const COMMON_MESSAGES = {
   /** 不在主 worktree 根目录 */
   NOT_MAIN_WORKTREE: '请在主 worktree 的根目录下执行 clawt',
+  /** 不在 git 仓库中 */
+  NOT_GIT_REPO: '当前目录不是 git 仓库，请先执行 git init 并提交后，再执行 clawt init 初始化项目',
   /** Git 未安装 */
   GIT_NOT_INSTALLED: 'Git 未安装或不在 PATH 中，请先安装 Git',
   /** Claude Code CLI 未安装 */

package/src/utils/validation.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import { MESSAGES } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { execCommand } from './shell.js';
-import { getGitCommonDir, isWorkingDirClean } from './git.js';
+import { getGitCommonDir, isInsideGitRepo, isWorkingDirClean } from './git.js';
 import { requireProjectConfig, guardMainWorkBranchExists } from './project-config.js';
 import { ensureOnMainWorkBranch } from './validate-branch.js';
@@ -25,20 +25,18 @@ export interface PreCheckOptions {
 /**
  * 校验当前目录是否为主 worktree 的根目录
- * 条件：git rev-parse --git-common-dir === ".git"
- * @throws {ClawtError} 不在主 worktree 根目录时抛出（包括不在 git 仓库中的情况）
+ * 先判断是否在 git 仓库中，再判断是否为主 worktree
+ * @throws {ClawtError} 不在 git 仓库时抛出 NOT_GIT_REPO
+ * @throws {ClawtError} 不在主 worktree 根目录时抛出 NOT_MAIN_WORKTREE
  */
 export function validateMainWorktree(): void {
-  try {
-    const gitCommonDir = getGitCommonDir();
-    if (gitCommonDir !== '.git') {
-      throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
-    }
-  } catch (error) {
-    if (error instanceof ClawtError) {
-      throw error;
-    }
-    // git 命令执行失败，可能不在 git 仓库中
+  // 先检查是否在 git 仓库中
+  if (!isInsideGitRepo()) {
+    throw new ClawtError(MESSAGES.NOT_GIT_REPO);
+  }
+  // 再检查是否在主 worktree 根目录
+  const gitCommonDir = getGitCommonDir();
+  if (gitCommonDir !== '.git') {
     throw new ClawtError(MESSAGES.NOT_MAIN_WORKTREE);
   }
 }

package/src/utils/worktree-matcher.ts CHANGED Viewed

@@ -10,7 +10,7 @@ import {
   SELECT_ALL_LABEL
 } from '../constants/index.js';
 import type { WorktreeInfo } from '../types/index.js';
-import { promptSelectBranch, promptMultiSelectBranches } from './ui-prompts.js';
+import { promptSelectBranch, promptGroupedMultiSelectBranches } from './ui-prompts.js';
 import type { GroupedChoice } from './ui-prompts.js';
 /**
@@ -90,7 +90,7 @@ export async function resolveTargetWorktrees(
     if (worktrees.length === 1) {
       return [worktrees[0]];
     }
-    return promptMultiSelectBranches(worktrees, messages.selectBranch);
+    return promptGroupedMultiSelectBranches(worktrees, messages.selectBranch);
   }
   // 1. 精确匹配优先
@@ -109,7 +109,7 @@ export async function resolveTargetWorktrees(
   // 2b. 多个匹配，交互多选
   if (fuzzyMatches.length > 1) {
-    return promptMultiSelectBranches(fuzzyMatches, messages.multipleMatches(branchName));
+    return promptGroupedMultiSelectBranches(fuzzyMatches, messages.multipleMatches(branchName));
   }
   // 3. 无匹配，抛出错误并列出所有可用分支

package/tests/unit/constants/messages.test.ts CHANGED Viewed

@@ -5,6 +5,7 @@ describe('MESSAGES', () => {
   describe('纯字符串消息', () => {
     const stringKeys = [
       'NOT_MAIN_WORKTREE',
+      'NOT_GIT_REPO',
       'GIT_NOT_INSTALLED',
       'CLAUDE_NOT_INSTALLED',
       'NO_WORKTREES',

package/tests/unit/utils/validation.test.ts CHANGED Viewed

@@ -5,9 +5,10 @@ vi.mock('../../../src/utils/shell.js', () => ({
   execCommand: vi.fn(),
 }));
-// mock git（validateMainWorktree 依赖 getGitCommonDir）
+// mock git（validateMainWorktree 依赖 getGitCommonDir 和 isInsideGitRepo）
 vi.mock('../../../src/utils/git.js', () => ({
   getGitCommonDir: vi.fn(),
+  isInsideGitRepo: vi.fn(),
 }));
 // mock project-config（runPreChecks 依赖 requireProjectConfig 和 guardMainWorkBranchExists）
@@ -22,30 +23,35 @@ vi.mock('../../../src/logger/index.js', () => ({
 }));
 import { execCommand } from '../../../src/utils/shell.js';
-import { getGitCommonDir } from '../../../src/utils/git.js';
+import { getGitCommonDir, isInsideGitRepo } from '../../../src/utils/git.js';
 import { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, runPreChecks } from '../../../src/utils/validation.js';
 import { requireProjectConfig, guardMainWorkBranchExists } from '../../../src/utils/project-config.js';
 import { ClawtError } from '../../../src/errors/index.js';
 const mockedExecCommand = vi.mocked(execCommand);
 const mockedGetGitCommonDir = vi.mocked(getGitCommonDir);
+const mockedIsInsideGitRepo = vi.mocked(isInsideGitRepo);
 const mockedRequireProjectConfig = vi.mocked(requireProjectConfig);
 const mockedGuardMainWorkBranchExists = vi.mocked(guardMainWorkBranchExists);
 describe('validateMainWorktree', () => {
-  it('.git 返回时正常通过', () => {
+  it('在主 worktree 根目录时正常通过', () => {
+    mockedIsInsideGitRepo.mockReturnValue(true);
     mockedGetGitCommonDir.mockReturnValue('.git');
     expect(() => validateMainWorktree()).not.toThrow();
   });
-  it('非 .git 时抛出 ClawtError', () => {
+  it('在子 worktree 中时抛出 NOT_MAIN_WORKTREE 错误', () => {
+    mockedIsInsideGitRepo.mockReturnValue(true);
     mockedGetGitCommonDir.mockReturnValue('/path/to/.git');
     expect(() => validateMainWorktree()).toThrow(ClawtError);
+    expect(() => validateMainWorktree()).toThrow('请在主 worktree 的根目录下执行 clawt');
   });
-  it('命令失败时抛出 ClawtError', () => {
-    mockedGetGitCommonDir.mockImplementation(() => { throw new Error('not a git repo'); });
+  it('不在 git 仓库中时抛出 NOT_GIT_REPO 错误', () => {
+    mockedIsInsideGitRepo.mockReturnValue(false);
     expect(() => validateMainWorktree()).toThrow(ClawtError);
+    expect(() => validateMainWorktree()).toThrow('当前目录不是 git 仓库');
   });
 });
@@ -87,6 +93,7 @@ describe('validateHeadExists', () => {
 describe('runPreChecks', () => {
   it('按选项组合调用对应校验', () => {
+    mockedIsInsideGitRepo.mockReturnValue(true);
     mockedGetGitCommonDir.mockReturnValue('.git');
     mockedExecCommand.mockReturnValue('abc1234');
     mockedRequireProjectConfig.mockReturnValue({ clawtMainWorkBranch: 'main' });