worktree-fleet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree Fleet

A skill for running N independent agents in parallel, each isolated in its own git worktree on its own branch. Independence is validated before anything spawns — if two workers declare overlapping

target_files

, the skill refuses with a clear conflict message.

这是一个可并行运行N个独立Agent的Skill，每个Agent都在独立的git worktree和git分支中隔离运行。在启动任何进程前会先验证独立性——如果两个工作进程声明的

target_files

存在重叠，该Skill会直接拒绝执行并给出明确的冲突提示。

Decision tree — which fleet?

决策树——选择哪种集群？

You want to run multiple agents in parallel. Which fleet?

1. Are the tasks independent (no shared files, no shared state)?
   YES → worktree-fleet  ← YOU ARE HERE
   NO  → continue

2. Does the work need iteration with a reviewer making accept/iterate decisions?
   YES → iterative-fleet
   NO  → continue

3. Is the work a one-shot DAG (each agent runs to completion, dependencies via depends_on)?
   YES → dag-fleet
   NO  → continue

4. None of the above?
   → You're the orchestrator. Open multiple Claude Code sessions.

你想要并行运行多个Agent，该选哪种集群？

1. 任务是否独立（无共享文件、无共享状态）？
   是 → worktree-fleet  ← 当前选择
   否 → 继续

2. 工作是否需要带审核循环的迭代（审核者可决定接受/迭代）？
   是 → iterative-fleet
   否 → 继续

3. 工作是否是一次性的DAG顺序任务（每个Agent运行至完成，通过depends_on定义依赖）？
   是 → dag-fleet
   否 → 继续

4. 以上都不符合？
   → 由你自行编排，打开多个Claude Code会话即可。

When to use THIS skill

何时使用本Skill

Tasks touch non-overlapping files (different modules, different docs, etc.)
You want merge-safe isolation — each worker on its own branch, no mid-flight conflicts possible
The merge decision is yours — after workers complete, you choose merge order / strategy
You want independent branches in git that you can inspect, cherry-pick, or discard

任务涉及互不重叠的文件（如不同模块、不同文档等）
你需要可安全合并的隔离环境——每个工作进程在独立分支上，不会出现运行中的冲突
合并决策由你掌控——工作进程完成后，你可以选择合并顺序和策略
你需要git中的独立分支，可自行检查、挑选或丢弃这些分支的更改

When NOT to use this skill

何时不使用本Skill

Workers need to coordinate or read each other's output →
```
dag-fleet
```
with
```
depends_on
```
Tasks overlap files (even partially) → fix the task split first, then come back
You want headless workers + reviewer-in-loop →
```
iterative-fleet
```
Work fits in the current conversation → use Claude Code's built-in Agent tool directly

工作进程需要协调或读取彼此的输出 → 使用带
```
depends_on
```
的
```
dag-fleet
```
任务涉及重叠文件（即使部分重叠）→ 先拆分任务，再使用本工具
你需要无头工作进程+审核循环 → 使用
```
iterative-fleet
```
工作内容可在当前对话中完成 → 直接使用Claude Code内置的Agent工具

fleet.json schema

json

{
  "fleet_name": "refactor-utils",
  "type": "worktree",
  "config": {
    "max_concurrent": 4,
    "model": "sonnet",
    "fallback_model": "haiku"
  },
  "workers": [
    {
      "id": "rename-foo",
      "task": "Rename foo() to baz() in src/utils/foo.ts and all callers",
      "target_files": ["src/utils/foo.ts", "src/**/*.test.ts"],
      "branch": "rename-foo-to-baz",
      "type": "code-run",
      "max_turns": 30,
      "max_budget_usd": 2.0
    }
  ]
}

New fields vs dag-fleet:

```
target_files
```
(required per worker) — list of file globs this worker will touch. Overlap across workers = launch refuses with exit 2.
```
branch
```
(required per worker) — git branch name for this worker's worktree. Must not already exist.

Worker type override (Claude only): Worktree workers always need Bash for

git commit

. If you set

type

read-only

write

, or

reviewer

, launch.sh will automatically override to

code-run

with a warning. The worktree itself provides isolation — Bash restrictions are unnecessary here. This override does not apply to codex workers (codex uses sandbox modes).

Provider support: Set

"provider": "codex"

at config or per-worker level to use OpenAI Codex CLI instead of Claude. Codex workers use

--sandbox workspace-write

(needed for git commit). See dag-fleet SKILL.md for full codex provider documentation (model aliases, reasoning_effort, limitations).

Default max_turns is 100 (not 50 like dag-fleet). Worktree workers typically edit, test, and commit — they need headroom.

json

{
  "fleet_name": "refactor-utils",
  "type": "worktree",
  "config": {
    "max_concurrent": 4,
    "model": "sonnet",
    "fallback_model": "haiku"
  },
  "workers": [
    {
      "id": "rename-foo",
      "task": "Rename foo() to baz() in src/utils/foo.ts and all callers",
      "target_files": ["src/utils/foo.ts", "src/**/*.test.ts"],
      "branch": "rename-foo-to-baz",
      "type": "code-run",
      "max_turns": 30,
      "max_budget_usd": 2.0
    }
  ]
}

与dag-fleet相比新增的字段：

```
target_files
```
（每个工作进程必填）——该工作进程会修改的文件通配符列表。如果不同工作进程的此列表存在重叠，启动时会直接拒绝并以状态码2退出。
```
branch
```
（每个工作进程必填）——该工作进程的worktree对应的git分支名称，该分支不能已存在。

Worker类型覆盖（仅Claude）： Worktree工作进程需要Bash来执行

git commit

。如果你将

type

设置为

read-only

、

write

或

reviewer

，launch.sh会自动将其覆盖为

code-run

并给出警告。worktree本身已提供隔离——此处无需Bash限制。此覆盖不适用于codex工作进程（codex使用沙箱模式）。

供应商支持： 在config或单个工作进程级别设置

"provider": "codex"

，即可使用OpenAI Codex CLI替代Claude。Codex工作进程使用

--sandbox workspace-write

（用于git commit）。关于codex供应商的完整文档（模型别名、推理能力、限制）请查看dag-fleet的SKILL.md。

默认max_turns为100（不同于dag-fleet的50）。Worktree工作进程通常需要编辑、测试和提交——需要更多的操作次数上限。

Available scripts

可用脚本

Script	When to call	Args
`launch.sh`	Validate independence, create worktrees, spawn workers in tmux	`<fleet-root> [--dry-run]`
`status.sh`	Per-worktree progress, cost, completion state	`<fleet-name-or-root> [--json]`
`merge.sh`	Print merge plan (files changed, line counts) — no auto-merge	`<fleet-name-or-root>`
`cleanup.sh`	Remove git worktrees, requires --force	`<fleet-name-or-root> --force`

脚本	调用时机	参数
`launch.sh`	验证独立性，创建worktree，在tmux中启动工作进程	`<fleet-root> [--dry-run]`
`status.sh`	查看每个worktree的进度、成本、完成状态	`<fleet-name-or-root> [--json]`
`merge.sh`	打印合并计划（修改的文件、行数统计）——不会自动合并	`<fleet-name-or-root>`
`cleanup.sh`	删除git worktree，需传入--force参数	`<fleet-name-or-root> --force`

Launch procedure

启动流程

Set
```
FLEET_ROOT
```
to an absolute path.
Create
```
$FLEET_ROOT/fleet.json
```
with the schema above.

For each worker, create

$FLEET_ROOT/workers/{id}/prompt.md

. Include:

Save ALL output to $FLEET_ROOT/workers/{id}/output/ — use absolute paths.

Run:

bash ${CLAUDE_SKILL_DIR}/scripts/launch.sh $FLEET_ROOT

```
--dry-run
```
validates independence without creating worktrees or spawning workers.
ALWAYS tell the user the exact status command so they can monitor manually:
```
bash ${CLAUDE_SKILL_DIR}/scripts/status.sh <fleet-name-or-root>
```
This is mandatory after every launch. The user must be able to check status without asking you.

IMPORTANT: Worker prompts MUST instruct the worker to commit its changes before exiting:

When you are done, commit your changes on the current branch with a descriptive message.

Without this, changes stay as unstaged modifications and cannot be merged via

git merge

将
```
FLEET_ROOT
```
设置为绝对路径。
在
```
$FLEET_ROOT
```
下创建
```
fleet.json
```
，格式遵循上述schema。

为每个工作进程创建

$FLEET_ROOT/workers/{id}/prompt.md

，并包含以下内容：

将所有输出保存至 $FLEET_ROOT/workers/{id}/output/ —— 使用绝对路径。

运行：

bash ${CLAUDE_SKILL_DIR}/scripts/launch.sh $FLEET_ROOT

```
--dry-run
```
参数可验证独立性，但不会创建worktree或启动工作进程。
必须告知用户确切的状态查询命令，以便他们手动监控：
```
bash ${CLAUDE_SKILL_DIR}/scripts/status.sh <fleet-name-or-root>
```
每次启动后都必须执行此操作，用户无需询问即可自行检查状态。

重要提示： 工作进程的提示必须包含在退出前提交更改的指令：

完成工作后，请在当前分支上提交更改并添加描述性的提交信息。

如果没有此指令，更改会保持为未暂存状态，无法通过

git merge

进行合并。

After workers complete

工作进程完成后

Run
```
merge.sh
```
to see what each branch changed.
Decide your merge strategy (in-order, cherry-pick, etc.).
Merge manually — the skill does NOT auto-merge.
Run
```
cleanup.sh --force
```
to remove worktrees.

运行
```
merge.sh
```
查看每个分支的更改内容。
决定你的合并策略（按顺序合并、挑选提交等）。
手动合并——本Skill不会自动合并。
运行
```
cleanup.sh --force
```
删除worktree。

Rationalizations to reject

需拒绝的不合理请求

Agent says	Rebuttal
"The tasks overlap slightly but I can manage"	Overlapping target_files = reject. No exceptions. Fix the task split first. If you think you can manage it, you're wrong — merge conflicts in parallel worktrees are unrecoverable.
"I'll skip `--dry-run` since I wrote the fleet.json carefully"	Then dry-run will be fast. Run it. The independence validator catches things you didn't think of (glob overlap, bidirectional fnmatch).
"Two workers both need the config file, but in different sections"	Same file = overlap. The validator doesn't know about "sections." Split the config change into a separate sequential step, or have one worker own it.
"I'll auto-merge since the branches are clean"	Never auto-merge. Run `merge.sh` , read the output, decide strategy. The whole point of worktree-fleet is that the operator owns the merge decision.
"I can skip cleanup — the worktrees aren't hurting anything"	Worktrees hold branch locks. Stale worktrees block future branch creation and waste disk. Run `cleanup.sh --force` when done.

Agent的说法	反驳理由
"任务只是略有重叠，但我可以处理"	只要 `target_files` 重叠就必须拒绝，没有例外。先拆分任务再说。如果你觉得自己能处理，那你错了——并行worktree中的合并冲突是无法恢复的。
"我已经仔细编写了fleet.json，可以跳过--dry-run吗"	Dry-run速度很快，一定要运行。独立性验证器能发现你没考虑到的问题（如通配符重叠、双向fnmatch匹配）。
"两个工作进程都需要修改配置文件，但修改的是不同部分"	同一文件即视为重叠。验证器无法识别“不同部分”。将配置文件的修改拆分为单独的顺序步骤，或由一个工作进程负责全部修改。
"分支很干净，我可以自动合并"	绝对不要自动合并。运行 `merge.sh` ，查看输出后再决定合并策略。Worktree-fleet的核心价值就是让操作者掌控合并决策。
"我可以不清理worktree——它们不会有什么影响"	Worktree会持有分支锁。残留的worktree会阻止未来创建分支，还会浪费磁盘空间。完成工作后务必运行 `cleanup.sh --force` 。

STRICT RULES

严格规则

Never skip
```
--dry-run
```
validation for new fleet configurations.
Never merge without reviewing
```
merge.sh
```
output first.
```
cleanup.sh
```
requires
```
--force
```
— no accidental removals.
Worktrees persist until you explicitly clean them up. They will not auto-remove.

$ARGUMENTS

对于新的集群配置，绝对不能跳过
```
--dry-run
```
验证。
绝对不能在未查看
```
merge.sh
```
输出的情况下进行合并。
```
cleanup.sh
```
必须传入
```
--force
```
参数——防止误删除。
Worktree会一直保留，直到你显式清理，不会自动删除。

$ARGUMENTS