/fleet

name: fleet
description: Fan out a fleet of independent agent-deck child sessions from inside a session and check their progress non-blockingly. Use when the user wants to "launch several/N sessions", "fan out", "run agents in parallel", "spin up a fleet", "kick off background agents", or "check progress from the main session" without blocking — covers launching parented children, polling status + completion via `session children`, and collecting results via `session output`.
metadata:
  compatibility: "claude, opencode"

Fleet

Fan out several independent agent-deck child sessions from inside your current session, keep working, and check their progress on demand — **without blocking** and **without consuming any delivery events**.

**Requires:** the `agent-deck session children` and `launch --assert-done` features. If `agent-deck session children --help` succeeds, you have them.

When to use

Use this when the user wants more than one agent working at once and wants to supervise from the parent session — e.g. "launch 5 sessions to each tackle a file", "fan out these tasks", "spin up a fleet and tell me when they're done".

This differs from the single sub-agent pattern in the `agent-deck` skill (one child + fire-&-forget / on-demand / blocking retrieval). Fleet is **many children + a non-blocking peek** across all of them.

**Run from inside an agent-deck session.** Launching auto-parents each child to the launching session, which is what makes them show up nested in the TUI and routes their completion back to you. (If you are not in a session, the children still launch but won't be grouped under a parent.)

**Need a *specific* parent?** Auto-parenting picks the launching session. To parent a child to a different session — e.g. fanning out under a named conductor, or launching from outside that session — pass `--parent <session-id-or-title>`. Spell out the long form: **never use the short `-p` to set a parent** (see the `-p` pitfall in Notes).

Before you fan out

• **Check for shared singletons.** N sessions on the same project can't truly run

in parallel if they serialize on one resource — a single dev DB, a bound port, one dev-server lock file. If they'd share one, either give each child isolated resources (own DB name + port) or run **one** coherent session instead of a fleet.

• **Worktree children need deps installed first.** A freshly created git worktree

has no `node_modules` / vendored deps. Make the **first instruction** in the child's `-m` prompt install them — and for a locked monorepo, install *from the frozen lockfile, never regenerate it* (e.g. `pnpm install --frozen-lockfile`). Otherwise the child's first test/build/e2e fails confusingly.

• **Long prompts: pass via a file.** For a big multi-line task, write it to a

file and pass `--message-file task.md` (or `--message-file -` to read stdin) instead of `-m`. The file is read directly by agent-deck, so backticks, `$`, and quotes never round-trip through the shell. Also works on `session start` and `session send` (there it replaces the positional message). On older builds without the flag, fall back to `-m "$(cat task.md)"`.

The loop

1. Fan out (one `launch` per child; loop it)

agent-deck launch <path> -c claude --inherit-group -m "<task for this child>"

• **Auto-parents** to your current session — children appear nested under you in

the TUI session list, each with its own live status.

• **Children land in your group automatically.** A child launched into a git

worktree auto-inherits the parent's group, so a worktree fleet stays co-located with you with no extra flags. For a non-worktree path that doesn't inherit, add `--inherit-group` to force it.

• **Do NOT pass a custom `-g/--group` for fleet children.** An explicit group

overrides inheritance and drops the child into its own detached group (e.g. a stray `fleet-issues` sitting next to — not under — your group). Leave the group off and let it inherit; only set `-g` when you deliberately want a child somewhere other than with the parent.

• **`--assert-done` is on by default for `-c claude`**: the child's message gets

a final-step instruction to print the completion sentinel (`===AGENTDECK_DONE=== status=ok summary=…`) so "done" is trustworthy.

• Run it N times (different `<path>` and `-m` per child) to fan out a fleet.

Useful flags:

• `--inherit-group` — force the parent's group for a non-worktree child (worktree

children already inherit automatically).

• `-t "<title>"` — give each child a readable title (otherwise auto-named).
• `--parent <id|title>` — explicitly parent the child to a specific session

instead of the auto-detected one. One step, no follow-up needed. **Long form only** — see the `-p` pitfall in Notes.

• `--no-assert-done` — skip the completion-sentinel instruction.
• `--no-parent` — launch a standalone top-level session you supervise directly,

not nested under you (you lose completion routing). **Set `-g` explicitly** for these — see "Independent (un-parented) sessions" below.

2. Keep working

Nothing blocks. Do other work in this session, in any chat, while the fleet runs.

3. Check progress (non-blocking, non-destructive)

agent-deck session children --json

Lists your sub-sessions with, per child: `id`, `title`, live `status` (running / waiting / idle / error), and the last asserted completion (`done_status` = ok|fail, `done_summary`, `done_at`). Defaults to the current session; pass an id/title to inspect another parent. **Read-only** — it never clears the inbox, so you can poll it as often as you like from any chat without disturbing the conductor or other readers.

A child with a `done_status` has finished and asserted its result.

**Prefer push over polling when your harness supports it.** Instead of re-running the check yourself, let the fleet notify you:

# One-shot "wake me when the whole fleet is finished" — run this in th