Fleet

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)

bashCopy code
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)

bashCopy code
agent-deck session children --json

Lists your sub-sessions with, per child: id, title, live status (running / waiting / idle / error), and last asserted completion history (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.

done_status records a prior assertion; it is not proof that the current turn is finished. Treat live running, queued, or unknown as still active even when completion history is present.

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

bashCopy code
# One-shot "wake me when the whole fleet is finished" — run this in the
# BACKGROUND (e.g. Claude Code's run_in_background Bash): it streams JSONL
# events and exits 0 once every child either needs input or is terminal
# (waiting, done sentinel, error, or stopped). The harness notifies you when
# it exits, so answer waiting children before starting another wait.
agent-deck session children --follow --until-done

# Live event stream for a long-running fleet — attach a stream watcher
# (e.g. Claude Code's Monitor tool) to this; each line is one event:
agent-deck session children --follow

--follow emits one JSON object per line: snapshot (initial state per child), added, status (from/to transition — including running → waiting, so you see a child stall on a question), done (completion sentinel, ok or fail), removed, error, plus a periodic heartbeat (default 60s, --heartbeat 0 disables) so silence always means "nothing changed", never "the watcher died". --interval tunes the poll cadence (default 2s). Failure states are on the stream too — filter for done alone and you'll miss crashed children; key off .event instead.

On older builds without --follow, fall back to a background until-loop:

bashCopy code
until agent-deck session children --json | jq -e 'all(.children[]; .done_status != null)' >/dev/null; do sleep 15; done

(Cloud-side schedulers — e.g. Claude Code routines — run on remote infra and cannot reach your local tmux/state.db; fleet supervision stays local.)

4. Unblock a child that's waiting on you

A child in waiting status has stopped and is asking for input (a question, a decision, a permission). This is pushed to you by default: a child's running → waiting transition is delivered to your inbox unless it was launched with --no-transition-notify. To answer it:

bashCopy code
# See what the child is asking:
agent-deck session output <child-id> --json
# Send the answer (child keeps running afterward):
agent-deck session send <child-id> "<your answer>"

# Codex numbered approval prompt: send one decision key, not composer text:
agent-deck session approve <child-id> once

session send flags: --wait (block until it finishes the turn, then print output), --stream (stream its JSONL events), --no-wait (fire and return), --draft (pre-fill the prompt without submitting). Default waits only until the child is ready to receive, then returns — so it does not freeze your session.

You can send follow-ups any time, not just when a child is waiting — e.g. to add scope, redirect, or course-correct a still-running child.

5. Collect a finished child's result

bashCopy code
agent-deck session output <child-id> --json

Returns that child's latest full response. Use it once session children shows the child is done (or any time you want its current output).

Worked example

bashCopy code
# Fan out 3 children, each on a different package:
agent-deck launch ./pkg/a -c claude --inherit-group -t "lint-a" -m "Fix all lint errors in this package."
agent-deck launch ./pkg/b -c claude --inherit-group -t "lint-b" -m "Fix all lint errors in this package."
agent-deck launch ./pkg/c -c claude --inherit-group -t "lint-c" -m "Fix all lint errors in this package."

# ...keep working, then whenever convenient:
agent-deck session children --json
#   → each child: status + done_status/done_summary

# If a child shows status "waiting", see its question and answer it:
agent-deck session output lint-a --json
agent-deck session send lint-a "Yes, drop the deprecated shim — don't keep a fallback."

# For each child reporting done, pull its result:
agent-deck session output lint-a --json

Independent (un-parented) sessions

Sometimes the user wants standalone sessions they supervise directly — not children of the conductor. Launch those with --no-parent. They run flat: no nesting in the TUI, and no completion routing back to your inbox.

The group trap. A parented worktree child auto-inherits the parent's group — that's why the parented-fleet rule is "never pass -g." With --no-parent there is no parent to inherit from, so a worktree session falls back to its cwd-derived group: the worktree's branch leaf (e.g. a stray issue-896 group sitting next to your real group instead of with its siblings).

So the rule inverts for independent sessions: pass the group explicitly. $AGENTDECK_RESOLVED_GROUP holds the launching session's group.

bashCopy code
agent-deck launch <path> -w <branch> --no-parent -g "$AGENTDECK_RESOLVED_GROUP" -c claude -m "..."

Or repair an already-launched stray, no restart needed:

bashCopy code
agent-deck group move <child-id> "$AGENTDECK_RESOLVED_GROUP"
agent-deck group delete <stray-group>        # once it's empty

Verify the group after any --no-parent worktree launch (ls --json is large; filter to the one session):

bashCopy code
agent-deck ls --json | jq -r '.[] | select(.title|test("<name>")) | "\(.title)\t\(.group)"'

Supervision tools the parent can use

All read-only / on-demand — none of them block your session:

• agent-deck session children [id] --json — the default monitor. Live status + last completion history per child. Non-destructive (never clears the inbox), so poll it as often as you like. Start here every heartbeat.
• agent-deck session children --follow [--until-done] — the push monitor. Streams JSONL child events (snapshot/added/status/done/removed/error + heartbeat) until interrupted; with --until-done it exits 0 once every child is waiting or terminal. Run it in the background for an intervention or completion wake-up, or attach a stream watcher for live events. Read-only like the plain form.
• agent-deck session output <id> --json — a child's latest full response.
• agent-deck session send <id> "<msg>" [--wait|--stream|--no-wait|--draft] — send a follow-up / answer a waiting child.
• agent-deck session approve <id> [once|always|session|N] — resolve one visibly active Codex approval menu. Do not use session send <id> "1": Codex consumes the digit as a decision key, while session send adds a trailing Enter that can land in the resumed turn.
• agent-deck status -q — global count of sessions currently waiting; a cheap coarse heartbeat across everything, not just your children.
• agent-deck inbox drain --json <your-session-id> — consumes the pushed completion events from your durable inbox (last-wins per child, deduped). Optional: session children already surfaces the same done_status without consuming anything, so only drain if you specifically want to clear the queue.
• agent-deck session stop <id> / agent-deck session remove <id> — teardown.

There is no always-on background watcher started for you — "monitored by default" means transition/completion events queue in your inbox; you still choose when to look (poll session children, or inbox drain).

Automatic turn-start snapshot (Claude conductors, newer builds). A Claude parent session gets a compact fleet snapshot injected as context on every prompt submit and session start — child counts plus actionable bullets for waiting (with the exact session output/session send commands) and completed children. This is state, complementing the Stop-edge inbox drain (events): it survives conductor restarts and works even if events were drained elsewhere. Leaf sessions see nothing. Opt a session out by launching it with AGENTDECK_NO_CHILDREN_CONTEXT=1 in its environment.

Notes

• Completion signal: trustworthy "done" comes from the child printing ===AGENTDECK_DONE=== status=<ok|fail> summary=<one line> as its last line. --assert-done (default-on for Claude) bakes this into the child's prompt; a child that never prints it shows live status but no done_status.
• Non-blocking by design: there is intentionally no "wait until all finish" command — checking is a cheap, repeatable query so a parent's other chats are never frozen.
• Grouping: worktree children inherit the parent's group automatically; for non-worktree paths add --inherit-group. Never pass a custom -g for a fleet child — it overrides inheritance and detaches the child into its own group. If a fleet did scatter (a stray group, or per-branch groups), move them back without restarting: agent-deck group move <child-id> <parent-group>, then agent-deck group delete <stray-group> once it's empty. (This "never pass -g" rule is for parented children; for --no-parent standalone sessions it inverts — you must set -g. See "Independent (un-parented) sessions".)
• The -p pitfall — use --parent, never -p, for a parent. -p is the global --profile shorthand, parsed before the subcommand. On older builds it swallows your intended parent id as a profile name and routes the child into a phantom ~/.agent-deck/profiles/<id>/state.db — the child runs in tmux but is invisible to the TUI / ls / session children (which read the default profile), and a retry then fails with "session already exists". The long-form --parent <id> is never affected and is the one-step way to set an explicit parent. If you already launched a child and need to (re)parent it after the fact, agent-deck session set-parent <id|title> <parent-id> also works. To clean up phantom DBs from a past -p slip: the orphaned rows live under profiles/<parent-id>/state.db; back up and remove that dir (the child's worktree/branch stay on disk).
• Stopping / cleanup: agent-deck session stop <id> and agent-deck session remove <id> (add --force if needed) tear a child down.

Backward Compatibility

Verified against v1.16.11-rc.2. agent-deck session children and launch --assert-done (the two hard requirements this skill states up front) have been stable for several releases — if agent-deck session children --help succeeds, you have them. --follow/--until-done are the newer, push-style additions: on a deck without them, fall back to the until-loop already shown above (until agent-deck session children --json | jq -e '...'; do sleep 15; done). session send's finer-grained --json delivery values (queued, delivered, unverified) are recent (see the agent-deck skill); on an older deck, treat any exit-0 send as "delivered, confirm separately" rather than branching on a confirmation field that may not exist yet.