Skip to main content
The Agent Squad layer turns Multi-Agent Orchestration into a real team. You give one prompt; the orchestrator plans the work into cards, dispatches specialist workers, watches where each one is, routes review feedback back to the coder, schedules follow-ups, and only delivers after validation — without you babysitting anything. It is built from four pieces, each usable on its own:

​
When does the squad activate?

There is no “squad switch” in the code — the orchestrator decides per turn, guided by a decision ladder taught in its system prompt (always present in /coder and /agent, since multi-agent mode is on by default). Knowing the ladder avoids the classic confusion of “I asked something and no cards appeared”: Two deterministic triggers also exist: high-complexity tasks fire Plan-and-Solve before the loop (a structured plan naturally becomes cards), and any [SQUAD MAIL] in the inbox is injected at the turn boundary with instructions to react before continuing.
You can always force it: /plan <goal> plans first, and an explicit instruction in the prompt — “create cards on the board and deliver this reviewed” — beats the heuristic. The middle ground is model judgment by design: the playbook gives a ruler, not a rigid if/else.

​
Live run registry — where is each agent?

Every agent execution registers itself in a process-wide registry: the orchestrator loop, each dispatched worker, delegate subagents, Mixture-of-Agents panel members and scheduler headless runs. Runs form a parent → child tree, and each one reports its current ReAct turn and the action in flight. The live dispatch panel uses it to show real progress per agent:

​
/agents

​
@agents (for the AI)

The orchestrator uses the same registry through the @agents tool (list, show, cancel) — so it can check what is already running before dispatching duplicate work, and kill a worker that is looping without progress. Cancellation is per-run: it cancels that run’s context and everything it spawned, never the whole batch.

​
Cross-process runs — see the gateway daemon from your REPL

When the Conversation Hub is enabled, each ChatCLI process mirrors its live runs into the shared hub database. /agents (and @agents) then list runs owned by other processes — a squad executing inside the gateway daemon, a scheduler headless run — in a dedicated section, tagged with their origin:
Every mirrored run carries a liveness heartbeat; if its process dies without finalizing, the entry is flagged (⚠ no heartbeat) instead of lying forever as “running”. /agents cancel works cross-process too: the request is flagged in the hub and the owning process honors it on its next sync tick (about a second). Run IDs embed a per-process instance token (run-<inst>-<n>), so two processes can never mint colliding IDs.

​
Driving the squad while it runs

The terminal is not locked while a squad (or any /coder run) is working: type /agents, /board, /mail or /jobs at any moment and the command executes right away — the live progress panel pauses, the output prints, the panel resumes. On macOS/Linux you also see what you type: the line being composed renders live on its own row below the panel or the turn spinner as ❯ your text▌, with backspace working — ChatCLI owns the line editing while the loop runs, so the spinner no longer eats your keystrokes. (Windows keeps the classic behavior: the line is delivered on Enter.)
Two rules keep this safe:
  • These four commands never reach the model or a pending security prompt — they are intercepted before the type-ahead queue, so typing /board at the wrong moment can never be read as a prompt answer or become an instruction to the LLM.
  • If the terminal is momentarily owned by a security confirmation, the command queues and runs at the next turn boundary (you’ll see ⚡ Applying N command(s) queued during the run).
/mail send <agent> <text> mid-run is the steering wheel: the directive lands in the recipient’s inbox and is delivered at its next ReAct turn — including agents running in another process, via the hub. Anything else you type mid-run keeps the existing behavior: it queues as type-ahead and is injected into the conversation as your next instruction at the turn boundary.

​
Work board — the squad’s kanban

The board is the shared unit of work: cards flowing across backlog → doing → review → blocked → done. A card carries an assignee (worker agent type), timestamped notes (review verdicts, delivery summaries), linked agent run IDs and scheduler job IDs, and its full transition history.
The AI manages the same board via @board (create, list, show, move, assign, note, link, archive). Agent results include their run_id, so the orchestrator links every execution to its card for traceability. Persistence is a single JSON document written atomically under ~/.chatcli/board.json (override with CHATCLI_BOARD_PATH). A corrupt file surfaces an error — it is never silently wiped.

​
Squad mail — agents talking to each other

Squad mail is a directed message bus between agents. Messages are injected into the recipient’s context at its next turn boundary — the only point that cannot split a native tool call and its result.
  • Workers get a universal native send_mail tool (regardless of their command allowlist): a reviewer can hand its verdict straight to the coder mid-flight.
  • The orchestrator drains its own inbox every turn (delivered as [SQUAD MAIL] blocks) and uses @mail (send, inbox, history).
  • You can redirect any agent without interrupting it:

​
Durable and cross-process

Squad mail is persisted through the Conversation Hub SQLite store (WAL mode): messages survive restarts and flow between processes. A directive typed in your REPL reaches agents running inside the Chat Gateway daemon, and vice versa. Delivery acks stop other processes (and post-restart hydration) from redelivering consumed messages.

​
The delivery playbook

With observability, a board and messaging in place, the orchestrator system prompt teaches the full autonomous cycle:
  1. Plan — break the goal into cards (@board create, one per deliverable, assignee = agent type).
  2. Develop — move the card to doing, dispatch the assigned workers, link the run_id.
  3. Review — move to review, dispatch reviewer/tester, record the verdict as a card note. Failed review → findings go back to the coder (new dispatch or @mail send coder), card returns to doing.
  4. Deliver — validate for real (build + tests, red → green), then move to done with a delivery note.
  5. Loop — repeat until no card sits outside done. Continuous or deferred work is scheduled via @scheduler with the job linked to its card.
The orchestrator is instructed to never end a run with unfinished cards unless they are in blocked with a note explaining the blocker.

​
Structured gateway telemetry

When the squad runs inside the Chat Gateway (Telegram, Slack, …), progress is emitted from typed agent events instead of scraping the rendered terminal output: reasoning lines, tool start/end with duration, plan counters, and one line per worker state change (current turn and action, then terminal status).
The legacy stdout-scraping path remains available with CHATCLI_GATEWAY_STRUCTURED_PROGRESS=false.

​
Configuration

All are surfaced in /config agent and /config gateway.
The squad tools are exposed to the LLM both in the prompt tool catalog and as native function-calling definitions (agents_runs, board_cards, squad_mail), so orchestration works on every provider.