clawt 1.0.0

package/.claude/agent-memory/docs-sync-updater/MEMORY.md

@@ -0,0 +1,48 @@
+# Docs Sync Updater - Agent Memory
+
+## 文档结构与对应关系
+
+### docs/spec.md
+- 完整的软件规格说明，包含 7 大章节
+- 命令流程在 `5. 需求场景详细设计` 下，每个命令一个子章节（5.1-5.8）
+- run 命令对应 `5.2 批量创建 Worktree + 执行 Claude Code 任务`，流程按步骤编号描述
+- merge 命令对应 `5.6 合并验证过的分支`，流程按步骤编号描述
+- 配置项说明在 `5.7 默认配置文件` 章节的表格中
+- 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
+
+### CLAUDE.md
+- 面向 Claude Code 的项目架构指引，精简扼要
+- run 命令流程在 `核心流程（run 命令）` 章节，编号列表描述
+- merge 和 run 中断清理在 `validate + merge 工作流` 章节，一行式描述用箭头连接流程
+- utils 目录描述用括号内逗号分隔列举功能模块
+- 更新模式：编号列表追加步骤，箭头链追加阶段，括号内追加关键词
+
+### README.md
+- 面向用户的使用文档
+- 每个命令一个 `###` 小节，含命令格式、参数表格、简要说明、示例
+- 配置文件说明在 `## 配置文件` 章节
+- 更新模式：更新命令说明段落，配置项表格
+
+## 关键约定
+- `autoDeleteBranch` 配置项影响三处：remove 命令、merge 命令、run 中断清理
+- merge 的清理确认在 merge 操作之前询问（避免交互中断），但清理在 merge 成功后执行
+- run 的中断清理在所有子进程退出后执行
+- 文档中文风格，技术术语保留英文（worktree, merge, branch, SIGINT 等）
+- cleanupWorktrees 是 merge 和 run 共用的公共清理函数（在 src/utils/worktree.ts）
+- killAllChildProcesses 是 run 专用的子进程终止函数（在 src/utils/shell.ts）
+
+## 配置项同步检查点
+
+配置项变更时需在以下 5 处保持一致：
+1. `src/constants/config.ts` — DEFAULT_CONFIG 对象
+2. `src/types/config.ts` — ClawtConfig 接口
+3. `docs/spec.md` — 5.7 默认配置文件章节（JSON 示例 + 配置项表格）
+4. `CLAUDE.md` — 关键约定段落中的配置描述
+5. `README.md` — 配置文件章节（JSON 示例 + 配置项表格）
+
+## run 命令双模式
+
+run 命令有两种模式（自 claudeCodeCommand 特性后）：
+- 不传 `--tasks`：交互式界面模式（单 worktree + `launchInteractiveClaude` + spawnSync）
+- 传 `--tasks`：并行任务模式（多 worktree + `executeClaudeTask` + spawnProcess）
+- CLAUDE.md 中的核心流程按模式分段描述

package/.claude/agents/docs-sync-updater.md

@@ -0,0 +1,128 @@
+---
+name: docs-sync-updater
+description: "Use this agent when the user explicitly requests to synchronize documentation files (docs/spec.md, CLAUDE.md, README.md) based on recent code changes in the working area or staging area. This agent must NEVER be called proactively or automatically — it must only be invoked when the user explicitly asks for documentation synchronization.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"请同步更新文档\"\\n  assistant: \"好的，我来调用文档同步 agent 来根据当前代码变更更新相关文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 2:\\n  user: \"代码改完了，帮我把文档也更新一下\"\\n  assistant: \"收到，我现在使用文档同步 agent 来分析代码变更并更新 docs/spec.md、CLAUDE.md 和 README.md。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 3:\\n  user: \"update docs based on my changes\"\\n  assistant: \"好的，我来启动文档同步 agent，根据工作区和暂存区的变更同步更新文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Counter-example (DO NOT do this):\\n  user: \"我刚加了一个新命令\"\\n  assistant: (DO NOT proactively launch this agent. Wait for the user to explicitly request documentation updates.)"
+model: opus
+memory: project
+---
+
+你是一位资深的技术文档工程师，精通代码变更分析与文档同步维护。你的核心职责是根据当前工作区（working directory）和暂存区（staging area）的代码修改，精准地同步更新项目中的三个关键文档：`docs/spec.md`、`CLAUDE.md` 和 `README.md`。
+
+## 重要约束
+
+- **绝对不允许删除注释掉的代码或解释性注释**。包括 `//` 和 `/* */` 形式的注释，这些可能在未来有用。
+- **新增的注释必须使用中文**。
+- **所有回复使用中文**。
+- 项目为纯 ESM（`"type": "module"`），模块导入需带 `.js` 后缀。
+- 常量应定义在项目的常量文件中（`src/constants/` 目录）。
+
+## 工作流程
+
+### 第一步：分析代码变更
+
+1. 运行 `git diff` 查看工作区中未暂存的变更。
+2. 运行 `git diff --cached` 查看暂存区的变更。
+3. 运行 `git diff HEAD` 查看所有相对于最新提交的变更。
+4. 如果以上都没有变更，运行 `git log -5 --oneline` 查看最近的提交，并分析最近一次提交的变更（`git diff HEAD~1 HEAD`）。
+5. 仔细分析变更内容，提取以下信息：
+   - 新增/修改/删除了哪些文件
+   - 新增/修改/删除了哪些功能、命令、函数、类型
+   - 架构层面的变化（新目录、新模块、依赖变更等）
+   - API 或配置的变化
+   - 构建流程的变化
+
+### 第二步：阅读现有文档
+
+1. 读取 `docs/spec.md` 的当前内容（如果存在）。
+2. 读取 `CLAUDE.md` 的当前内容。
+3. 读取 `README.md` 的当前内容（如果存在）。
+4. 理解每个文档的结构、风格和覆盖范围。
+
+### 第三步：确定需要更新的内容
+
+对每个文档，判断代码变更是否影响其内容：
+
+- **`CLAUDE.md`**：项目架构说明、命令列表、核心流程、目录层级、关键约定、构建命令等。当新增命令、修改架构、调整目录结构、修改构建流程时需要更新。
+- **`docs/spec.md`**：项目规格说明文档。当功能需求、技术规格、API 设计发生变化时需要更新。
+- **`README.md`**：用户面向的项目说明。当用户可见的功能、安装方式、使用方法、命令参数发生变化时需要更新。
+
+### 第四步：执行更新
+
+1. **保持文档原有风格和格式**——不要改变文档的整体结构和语气。
+2. **只修改与代码变更相关的部分**——不要重写整个文档。
+3. **增量更新**——新增内容放在逻辑上合适的位置。
+4. **保持一致性**——术语、格式、缩进与现有文档保持一致。
+5. **如果某个文档不需要更新，明确说明原因并跳过**。
+
+### 第五步：输出更新摘要
+
+完成所有文档更新后，输出一份简洁的更新摘要：
+- 列出每个文档的具体修改内容
+- 如果某个文档未做修改，说明原因
+
+## 文档更新原则
+
+1. **准确性优先**：文档内容必须准确反映代码的实际状态，不要编造或猜测。
+2. **最小变更原则**：只更新与代码变更直接相关的部分，避免不必要的改动。
+3. **向后兼容**：保留现有文档中仍然有效的内容，不要随意删除。
+4. **中文优先**：新增的文档内容使用中文，除非原文档使用英文且保持一致性更好。
+5. **代码示例同步**：如果文档中有代码示例受到变更影响，必须同步更新。
+
+## 质量检查
+
+在完成更新前，自我检查：
+- [ ] 所有变更的功能是否都在相关文档中体现？
+- [ ] 文档中的代码示例是否仍然正确？
+- [ ] 命令列表、参数说明是否与代码一致？
+- [ ] 目录结构描述是否与实际一致？
+- [ ] 没有删除任何注释掉的代码或解释性注释？
+- [ ] 新增注释是否使用中文？
+- [ ] 文档格式是否与原有风格保持一致？
+
+## 边界情况处理
+
+- 如果工作区和暂存区都没有变更，检查最近的提交并告知用户当前没有未提交的变更，询问是否基于最近提交更新。
+- 如果某个文档文件不存在，告知用户并询问是否需要创建。
+- 如果变更内容过于复杂或不确定如何反映到文档中，列出你的理解并询问用户确认。
+- 如果变更只涉及代码重构而不改变功能，可能不需要更新面向用户的文档（README.md），但可能需要更新架构文档（CLAUDE.md）。
+
+**Update your agent memory** as you discover documentation patterns, document structure conventions, terminology usage, and relationships between code modules and their documentation sections. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
+
+Examples of what to record:
+- 各文档的章节结构和更新模式
+- 项目术语和命名惯例
+- 代码模块与文档章节的对应关系
+- 常见的文档更新场景和处理方式
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/qihoo/Documents/A_Own/clawt/.claude/agent-memory/docs-sync-updater/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work, temporary state)
+- Information that might be incomplete — verify against project docs before writing
+- Anything that duplicates or contradicts existing CLAUDE.md instructions
+- Speculative or unverified conclusions from reading a single file
+
+Explicit user requests:
+- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
+- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

package/CLAUDE.md

@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+Clawt 是一个 CLI 工具，融合 Git Worktree 与 Claude Code CLI，支持在本地并行执行多个 Claude Code Agent 任务。核心思路：为每个任务创建独立的 git worktree，在各自隔离的环境中并行调用 `claude -p` 执行任务，互不干扰。
+
+## 构建与开发
+
+```bash
+npm run build     # 使用 tsup 构建到 dist/
+npm run dev       # tsup --watch 模式
+npm i -g .        # 本地全局安装进行测试
+```
+
+构建工具为 tsup，入口 `src/index.ts`，输出 ESM 格式，target node18。构建产物在 `dist/index.js` 带有 shebang 头。另有 `scripts/postinstall.ts` 作为独立入口构建（npm 安装后初始化 `~/.clawt/` 目录）。
+
+本项目无测试框架和 lint 工具。
+
+## 架构
+
+### 命令注册模式
+
+每个命令为独立文件 `src/commands/<name>.ts`，导出 `registerXxxCommand(program)` 函数，在 `src/index.ts` 中统一注册到 Commander。命令内部逻辑封装在对应的 `handleXxx` 函数中。
+
+六个命令：`create`、`run`、`list`、`remove`、`validate`、`merge`。
+
+### 核心流程（run 命令）
+
+run 命令有两种模式：
+
+**模式一：不传 `--tasks`（交互式界面模式）**
+
+1. `validateMainWorktree()` 确认在主 worktree 根目录
+2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
+3. `createWorktrees()` 创建单个 worktree
+4. `launchInteractiveClaude()` 通过 `spawnSync` + `inherit stdio` 在 worktree 中直接启动 Claude Code 交互式界面（启动命令由配置项 `claudeCodeCommand` 指定，默认 `claude`）
+
+**模式二：传 `--tasks`（并行任务模式）**
+
+1. `validateMainWorktree()` 确认在主 worktree 根目录
+2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
+3. `createWorktrees()` 批量创建 git worktree（串行）
+4. `executeClaudeTask()` 通过 `spawnProcess` 并行调用 `claude -p <task> --output-format json --permission-mode bypassPermissions`
+5. 每个任务完成时实时输出通知，全部完成后输出汇总
+6. SIGINT（Ctrl+C）中断处理：`killAllChildProcesses()` 终止所有子进程 → 等待退出 → `handleInterruptCleanup()` 根据 `autoDeleteBranch` 配置自动或交互式清理 worktree 和分支
+
+### validate + merge 工作流
+
+- `validate`：将目标 worktree 的变更通过 git stash 迁移到主 worktree，便于在主 worktree 中测试
+- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ 合并到主 worktree → pull → push → 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）
+- `run` 中断清理：Ctrl+C 终止所有子进程后，根据 `autoDeleteBranch` 配置自动清理或交互式确认清理本次创建的 worktree 和分支
+
+### 目录层级
+
+- `src/commands/` — 各命令的注册与处理逻辑
+- `src/utils/` — 工具函数（git 操作、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出、交互式输入）
+- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列）
+- `src/types/` — TypeScript 类型定义
+- `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
+- `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）
+
+### 关键约定
+
+- 所有命令执行前都会调用 `validateMainWorktree()` 确保在主 worktree 根目录（`git rev-parse --git-common-dir === ".git"`）
+- Worktree 统一存放在 `~/.clawt/worktrees/<projectName>/` 下
+- 全局配置文件 `~/.clawt/config.json`，postinstall 时自动创建/合并，包含 `autoDeleteBranch`（是否自动删除分支）和 `claudeCodeCommand`（Claude Code CLI 启动指令）两个配置项
+- shell 命令执行有同步（`execCommand` → `execSync`）和异步（`spawnProcess` → `spawn`）两种方式
+- 项目为纯 ESM（`"type": "module"`），模块导入需带 `.js` 后缀
+- 分支名特殊字符会被 `sanitizeBranchName()` 自动清理

package/README.md

@@ -0,0 +1,168 @@
+# Clawt
+
+基于本地 Git 项目创建多个隔离的 worktree 环境，并行执行多个 Claude Code Agent 任务，所有 Agent 的代码修改互不干扰。
+
+## 安装
+
+```bash
+npm i -g clawt
+```
+
+**环境要求：**
+
+- Node.js >= 18
+- Git >= 2.15
+- Claude Code CLI（仅 `clawt run` 需要）
+
+## 使用前提
+
+所有命令**必须在主 worktree 的仓库根目录**下执行（即包含 `.git` 目录的原始仓库）。在子 worktree 或子目录中执行会被拒绝。
+
+## 命令
+
+### `clawt create` — 批量创建 worktree
+
+```bash
+clawt create -b <branchName> [-n <count>]
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `-b` | 是 | 分支名 |
+| `-n` | 否 | 创建数量，默认 `1` |
+
+创建 1 个时，分支名即为 `<branchName>`；创建多个时，分支名会自动加后缀编号：`<branchName>-1`、`<branchName>-2`……
+
+```bash
+# 创建 1 个 worktree
+clawt create -b feature-login
+
+# 创建 3 个 worktree
+clawt create -b feature-scheme -n 3
+```
+
+### `clawt run` — 批量创建 worktree + 并行执行 Claude Code 任务
+
+```bash
+# 多任务并行
+clawt run -b <branchName> --tasks <task1> --tasks <task2> --tasks <task3>
+
+# 单 worktree + Claude Code 交互式界面
+clawt run -b <branchName>
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `-b` | 是 | 分支名 |
+| `--tasks` | 否 | 任务描述，可多次指定，任务数量即 worktree 数量。不传则在 worktree 中打开 Claude Code 交互式界面 |
+
+每个 `--tasks` 对应一个独立的 worktree，Claude Code 会在各自隔离的环境中并行执行任务。任务完成后会实时通知结果，全部完成后输出汇总信息。
+
+不传 `--tasks` 时会创建单个 worktree，并在其中直接启动 Claude Code 交互式界面（通过 `spawnSync` + `inherit stdio`），让用户与 Claude Code 直接交互。启动命令由配置项 `claudeCodeCommand` 指定（默认 `claude`）。
+
+任务执行过程中按 Ctrl+C 可中断所有任务。中断后会根据配置自动清理或询问是否清理本次创建的 worktree 和分支（`autoDeleteBranch: true` 时自动清理）。
+
+```bash
+# 多任务并行
+clawt run -b feature-scheme \
+  --tasks "实现用户登录功能" \
+  --tasks "实现用户注册功能" \
+  --tasks "实现密码重置功能"
+
+# 单 worktree，打开 Claude Code 交互式界面
+clawt run -b feature-login
+```
+
+### `clawt validate` — 在主 worktree 验证分支变更
+
+```bash
+clawt validate -b <branchName>
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `-b` | 是 | 要验证的分支名 |
+
+将目标 worktree 的变更通过 `git stash` 迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。
+
+```bash
+clawt validate -b feature-scheme-1
+```
+
+### `clawt merge` — 合并分支到主 worktree
+
+```bash
+clawt merge -b <branchName> [-m <commitMessage>]
+```
+
+| 参数 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `-b` | 是 | 要合并的分支名 |
+| `-m` | 否 | 提交信息（目标 worktree 工作区有修改时必填） |
+
+将目标 worktree 的变更合并到主 worktree 的当前分支，并推送到远程仓库。如果目标 worktree 工作区有未提交的修改，需要通过 `-m` 提供提交信息；如果目标 worktree 已经提交过（工作区干净但有本地提交），可以省略 `-m` 直接合并。merge 成功后会询问是否清理对应的 worktree 和分支（如果配置了 `autoDeleteBranch: true` 则自动清理）。
+
+```bash
+# 目标 worktree 有未提交修改，需提供 -m
+clawt merge -b feature-scheme-1 -m "feat: 实现用户登录功能"
+
+# 目标 worktree 已提交过，可省略 -m
+clawt merge -b feature-scheme-1
+```
+
+### `clawt remove` — 移除 worktree
+
+```bash
+clawt remove [options]
+```
+
+支持三种移除粒度：
+
+```bash
+# 移除当前项目下所有 worktree
+clawt remove --all
+
+# 移除指定分支名下的所有 worktree
+clawt remove -b feature-scheme
+
+# 移除指定分支名的某一个 worktree
+clawt remove -b feature-scheme -i 2
+```
+
+移除时会询问是否同时删除对应的本地分支。
+
+### `clawt list` — 列出当前项目所有 worktree
+
+```bash
+clawt list
+```
+
+列出当前项目在 `~/.clawt/worktrees/` 下的所有 worktree 及对应分支。
+
+## 配置文件
+
+安装后会自动在 `~/.clawt/config.json` 生成全局配置文件：
+
+```json
+{
+  "autoDeleteBranch": false,
+  "claudeCodeCommand": "claude"
+}
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| ------ | ---- | ------ | ---- |
+| `autoDeleteBranch` | `boolean` | `false` | 移除 worktree 时自动删除对应本地分支；merge 成功后自动清理 worktree 和分支；run 中断后自动清理本次创建的 worktree 和分支 |
+| `claudeCodeCommand` | `string` | `"claude"` | Claude Code CLI 启动指令，用于 `clawt run` 不传 `--tasks` 时在 worktree 中打开交互式界面 |
+
+## 分支名规则
+
+分支名中的特殊字符（`/`、`.`、空格、`~` 等）会被自动替换为 `-`，连续的 `-` 会被压缩，首尾 `-` 会被去除。发生转换时会在终端提示。
+
+```
+feature/a.b  →  feature-a-b
+```
+
+## 日志
+
+日志保存在 `~/.clawt/logs/` 目录，按日期滚动，保留 30 天。