clawt 3.9.13 → 3.10.1

package/README.md

@@ -1,9 +1,87 @@
 # Clawt
 
+[![npm version](https://img.shields.io/npm/v/clawt.svg)](https://www.npmjs.com/package/clawt) [![GitHub](https://img.shields.io/badge/GHub-afk101%2Fclawt-blue)](https://github.com/afk101/clawt)
+
 **[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.
 
+> When AI coding assistants are already smart enough, the bottleneck is no longer "can it do this" — it's "how many things can you have it do at once."
+
+## Why Clawt
+
+Claude Code can independently complete feature development, bug fixes, and refactoring. But in real projects, you rarely face a single task — you face an entire iteration cycle with **multiple independent tasks that could run in parallel**:
+
+- Replace message list with virtual list
+- Implement publish/deploy dialog
+- Fix navbar flicker bug
+- ………………
+
+This is how most developers use Claude Code today — **serial execution**:
+
+![Serial timeline](https://p5.ssl.qhimg.com/d/inn/20812850b163/2026-03-22-16-00-00-serial-timeline.png)
+
+**3 tasks total ≈ 49.5 min.** The biggest problem: **while Claude is working on task A, B, C — you're just waiting.**
+
+Running multiple tasks in the same repo simultaneously isn't recommended either — there's only one Git working tree, files can conflict, and commits would mix multiple independent tasks together.
+
+## Clawt's Parallel Mode
+
+The core idea is simple:
+
+> **Use Git Worktree to create an isolated working directory for each task, letting multiple Claude Code Agents work in parallel on their own branches — without interfering with each other.**
+
+Same 3 tasks, with Clawt:
+
+![Parallel timeline](https://p5.ssl.qhimg.com/d/inn/737a5d53c9a0/2026-03-22-15-34-32-parallel-timeline.png)
+
+**3 tasks total ≈ 26.5 min (parallel execution, sequential review)**
+
+| Mode | 3 tasks | 10 tasks |
+|------|---------|----------|
+| Serial | ~49.5 min | ~165 min |
+| **Clawt parallel** | **~26.5 min** | **~65 min** |
+| Speedup | **1.9×** | **2.5×** |
+
+The more tasks, the bigger the advantage. In serial mode, **you wait for AI**. In parallel mode, **AI waits for you**.
+
+## Why Git Worktree?
+
+Can't you just open multiple terminals and clone multiple copies? You can — but Git Worktree is the cleaner solution:
+
+| Approach | Disk usage | Git history | Branch mgmt | Merge |
+|----------|-----------|-------------|-------------|-------|
+| Multiple `git clone` | Full copy per repo (hundreds of MB ~ GB) | Independent, needs remote sync | Separate, messy | Requires push/pull across repos |
+| **Git Worktree** | Shared `.git` objects, minimal overhead | **Shared** | **Unified** | Local branch merge, instant |
+
+Git Worktree is a native Git mechanism (`git worktree add`) that creates multiple working directories under one repo, each on its own branch, sharing the same `.git` object database — low disk usage, fast local operations.
+
+## Design Philosophy
+
+> **Human's job: think about requirements, write prompts, review code(Optional). AI's job: write code. Git Worktree is the isolation layer between them.**
+
+![Architecture](https://p0.ssl.qhimg.com/t11b673bcd66632b91c744dad9c.png)
+
+> **Clawt does not modify, replace, or wrap Claude Code itself. It only manages "where" and "how many" Claude Code instances run — at a higher level.**
+
+![Layer architecture](https://p4.ssl.qhimg.com/d/inn/1e5b09fd7000/clawt-layer-architecture.png)
+
+Everything you use inside each worktree is vanilla Claude Code — same interaction, same commands, same `CLAUDE.md`, same MCP config. Any Claude Code update automatically benefits Clawt with zero adaptation needed.
+
+The workflow maps directly to standard Git practices:
+
+```
+┌─────────────┐    ┌──────────────────┐    ┌───────────────┐
+│  clawt run   │───►│ clawt validate   │───►│  clawt merge   │
+│  AI develops │    │  Human reviews   │    │  Merge to main │
+│  on branch   │    │  in main worktree│    │  Clean branch  │
+└─────────────┘    └──────────────────┘    └───────────────┘
+```
+
+- **`validate`**: equivalent to Code Review — view diff, run tests in the main worktree (works perfectly with hot reload)
+- **`cover`**: for simple fixes (styling, constants), edit directly in the main worktree and push changes back to the target worktree
+- **`merge`**: merge to main, each merge maps to one clear feature/fix — clean Git history
+
 ## Installation
 
 ```bash
@@ -40,7 +118,7 @@ clawt status -i
 | `q` | Quit panel | — |
 
 Example:
-![](https://p3.ssl.qhimg.com/d/inn/8a3779be2486/upload_screenshot_1772675658.png)
+![](https://p1.ssl.qhimg.com/d/inn/5c6aaa8400cf/upload_screenshot_1779703026.png)
 > All operations can also be executed via standalone commands — see "Command Reference" below.
 
 ## Command Reference
@@ -335,6 +413,7 @@ Configuration file is located at `~/.clawt/config.json`, auto-generated after in
 
 | Config Item | Default | Description |
 | ------ | ------ | ---- |
+| `language` | `"en"` | Interface language: `en` (English) / `zh-CN` (Chinese) |
 | `autoDeleteBranch` | `false` | Auto-delete merged/removed branches |
 | `claudeCodeCommand` | `"claude"` | Claude Code CLI launch command (can be overridden per-project via `clawt init show`) |
 | `autoPullPush` | `false` | Auto pull/push after merge |

package/README.zh-CN.md

@@ -1,9 +1,89 @@
 # Clawt
 
+[![npm version](https://img.shields.io/npm/v/clawt.svg)](https://www.npmjs.com/package/clawt) [![GitHub](https://img.shields.io/badge/GHub-afk101%2Fclawt-blue)](https://github.com/afk101/clawt)
+
 [English](./README.md) | **[中文](./README.zh-CN.md)**
 
 基于 Git Worktree 并行执行多个 Claude Code Agent 任务，所有 Agent 的代码修改互不干扰。
 
+> 当 AI 编程助手已经足够聪明，瓶颈就不再是"它能不能做"，而是"你能同时让它做多少件事"。
+
+## 为什么需要 Clawt
+
+Claude Code 可以独立完成需求开发、Bug 修复、代码重构等任务。但在实际项目开发中，我们往往面对的不是一个任务，而是一整个迭代周期里的**多个可以并行的独立任务**：
+
+- 消息列表替换为虚拟列表
+- 完成发布、部署弹窗
+- 修复导航栏闪烁 bug
+- ………………
+
+这是大多数开发者使用 Claude Code 的现状——**串行执行**：
+
+![串行模式时间轴](https://p5.ssl.qhimg.com/d/inn/20812850b163/2026-03-22-16-00-00-serial-timeline.png)
+
+**3 个任务总耗时 ≈ 49.5 分钟**。最大的问题是：**Claude 在执行任务的时候，你完全在干等。**
+
+而且不推荐在同一个代码仓库里同时开始多个任务，因为 Git 工作区只有一个，文件可能互相冲突。
+
+## Clawt 的并行模式
+
+核心思路非常简单：
+
+> **利用 Git Worktree 为每个任务创建独立的工作目录，让多个 Claude Code Agent 在各自隔离的分支上并行工作，互不干扰。**
+
+同样的 3 个任务，使用 Clawt 后：
+
+![并行模式时间轴](https://p5.ssl.qhimg.com/d/inn/737a5d53c9a0/2026-03-22-15-34-32-parallel-timeline.png)
+
+**3 个任务总耗时 ≈ 26.5 分钟（并行执行，串行验证）**
+
+| 模式 | 3 个任务 | 10 个任务 |
+|------|---------|----------|
+| 串行模式 | ~49.5 分钟 | ~165 分钟 |
+| **Clawt 并行** | **~26.5 分钟** | **~65 分钟** |
+| 效率提升 | **1.9×** | **2.5×** |
+
+一定范围内，**任务越多，并行的优势越大**。
+
+核心差别一目了然：**串行模式下，人在等 AI；并行模式下，AI 在等你。**
+
+## 为什么是 Git Worktree？
+
+多开几个终端、多 clone 几份代码不也能并行吗？可以，但 Git Worktree 是更优雅的方案：
+
+| 方案 | 磁盘占用 | Git 历史 | 分支管理 | 合并难度 |
+|------|---------|---------|---------|---------|
+| 多次 `git clone` | 每份完整副本（几百 MB ~ 几 GB） | 各自独立，需要 remote 同步 | 各自独立，容易混乱 | 需要 push/pull 跨仓库操作 |
+| **Git Worktree** | 共享 `.git` 对象库，增量极小 | **共享同一份** | **统一管理** | 本地分支直接 merge |
+
+Git Worktree 是 Git 原生支持的机制（`git worktree add`），它允许在同一个仓库下创建多个工作目录，每个目录 checkout 不同的分支，但**共享同一个 `.git` 对象数据库**。磁盘占用低，分支切换和合并都是本地操作，速度极快。
+
+## 设计哲学
+
+> **人做的事情：思考需求、写 Prompt、审查代码（可选）。AI 做的事情：写代码。用 Git Worktree 作为两者之间的隔离层。**
+
+![架构图](https://p0.ssl.qhimg.com/t11b673bcd66632b91c744dad9c.png)
+
+> **Clawt 不修改、不替换、不包装 Claude Code 本身。它只是在更高一层管理"在哪里"以及"同时启动多少个" Claude Code。**
+
+![分层架构](https://p4.ssl.qhimg.com/d/inn/1e5b09fd7000/clawt-layer-architecture.png)
+
+你在每个 Worktree 里使用的，就是原汁原味的 Claude Code——同样的交互方式、同样的命令、同样的 CLAUDE.md、同样的 MCP 配置。Claude Code 的任何更新，Clawt 自动受益，无需适配。
+
+Clawt 的工作流直接映射到标准 Git 开发规范：
+
+```
+┌─────────────┐    ┌──────────────────┐    ┌───────────────┐
+│  clawt run   │───►│ clawt validate   │───►│  clawt merge   │
+│  AI 在分支上  │    │  人在主 worktree  │    │  合入主分支     │
+│  独立开发     │    │  审查变更         │    │  清理分支       │
+└─────────────┘    └──────────────────┘    └───────────────┘
+```
+
+- **`validate`**：相当于 Code Review，在主 Worktree 中查看 diff、运行测试、确认质量（可以完美契合热更新）
+- **`cover`**：如有简单修改（改样式、改常量等），直接在主 worktree 改完推回目标 worktree，形成"AI 写 → 人审 → 人修 → AI 继续"的协作循环
+- **`merge`**：合入主分支，每个 merge 对应一个明确的功能或修复，Git 历史一目了然
+
 ## 安装
 
 ```bash
@@ -335,6 +415,7 @@ clawt alias remove l
 
 | 配置项 | 默认值 | 说明 |
 | ------ | ------ | ---- |
+| `language` | `"en"` | 界面语言：`en`（英文） / `zh-CN`（中文） |
 | `autoDeleteBranch` | `false` | 自动删除已合并/已移除的分支 |
 | `claudeCodeCommand` | `"claude"` | Claude Code CLI 启动命令 |
 | `autoPullPush` | `false` | merge 后自动 pull/push |