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.

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