stevengonsalvez ainb fleet — overview
Single Rust binary (ainb) provides orchestration verbs across every
claude session running on this host. Each verb has its own colon-namespaced
sub-skill with focused docs.
Verbs
| sub-skill | what it does |
|---|---|
/ainb-fleet:ainb-spawn |
Spawn a session correctly with ainb run (always into a worktree, and the --parent shapes that silently misfire) |
/ainb-fleet:standup |
List every claude session — merged across ainb · peers · bg jobs |
/ainb-fleet:broadcast |
Send one prompt to selected sessions |
/ainb-fleet:sequence |
Ordered multi-step prompts, ack-gated between steps |
/ainb-fleet:needs |
Show sessions blocked on input / errors / waiting |
/ainb-fleet:atc |
Air Traffic Control — the persistent brain: watches the fleet on a heartbeat, auto-clears safe sessions, escalates the rest to your phone |
/ainb-fleet:daemon |
Background auto-continue watcher (superseded by ATC for managed fleets) |
ATC is the orchestrating brain that drives the other verbs on a schedule. The verbs are its hands/eyes; the phone bridge is its voice to you. Reach for ATC when you want unattended, policy-driven fleet supervision; reach for the individual verbs for one-off actions.
Architecture (1-line)
discover (ainb + peers + jobs) ──▶ state read ──▶ send (tmux-first, broker fallback)
Global flag
--format json|text|csv|markdown (default text). Prefer --format json
when an LLM is the consumer.
Transport — tmux is primary
Writes (broadcast / sequence / daemon / answer-routing) go out over tmux
send-keys by default. The claude-peers broker is opt-in / fallback only,
because in practice it has proven flaky (silent delivery gaps). The primitives
the fleet uses are exactly: tmux send-keys -l (write), tmux capture-pane -p -S -<n> (read, incl. scrollback), and the session JSONL transcript
(~/.claude/projects/<cwd-slug>/<sid>.jsonl) as ground-truth read.
Select the write channel with AINB_FLEET_TRANSPORT:
| value | behaviour |
|---|---|
unset / tmux / tmux-first |
tmux send-keys first, broker fallback (default) |
tmux-only |
tmux send-keys only — never touch the broker |
peers / broker / peers-first |
legacy: broker first, tmux fallback |
┌──────────────┐ tmux send-keys -l ┌─────────────┐
send ────▶│ tmux pane? │─────────────────────▶│ delivered │
└──────┬───────┘ └─────────────┘
│ no live pane (or peers-first)
▼
┌──────────────┐ broker /send-message ┌─────────────┐
│ peer + broker│──────────────────────▶│ delivered │
│ healthy? │ └─────────────┘
└──────────────┘
Discovery sources
Discovery is independent of the write transport — peers are still read for
visibility (PID, summary, WAITING: markers) even when writes go via tmux.
- ainb — every session ainb has spawned via
ainb run - peers — sessions registered with the claude-peers broker (
~/.claude-peers.db), read directly from its sqlite (no HTTP), so discovery survives a down broker - jobs — bg-session dirs under
~/.claude/jobs/
Merged + deduped by cwd so the same session in two sources collapses
into one record with sources: ["ainb", "peers"].
Environment overrides
| var | default | use |
|---|---|---|
AINB_BIN |
ainb |
override binary the discover layer shells to (tests) |
AINB_FLEET_TRANSPORT |
tmux-first |
write channel: tmux / tmux-only / peers |
AINB_FLEET_PEER_ID |
ainb-fleet-cp |
from-id used when a write does fall back to the broker |
AINB_FLEET_JOBS_DIR |
~/.claude/jobs |
bg-job scan root |
CLAUDE_PEERS_DB |
~/.claude-peers.db |
broker sqlite path (discovery) |
CLAUDE_PEERS_PORT |
7899 |
broker HTTP port (fallback writes only) |
See also
ainb list— lifecycle-only session list (no peer/jobs enrichment)ainb attach <workspace>— drop into a session's tmuxainb kill <workspace>— terminate a single session by exact name