asheshgoplani / 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)"'

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](../agent-deck/references/gotchas.md#backward-compatibility)); 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.