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)

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 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:

# 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:

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:

# 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

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

# 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.

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

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

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):

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