Orchestrator agent

Let one agent run the others. The orchestrator plans the work, starts sub-agents with the beswarm CLI, waits on them and merges their results — while you watch the tree form in the Agents panel.

Teach the orchestrator BeSwarm

BeSwarm ships a skill that teaches an agent to drive sessions, workspaces, worktrees and agents. Either:

• turn on Settings → Agents → Auto learn BeSwarm's skills, so agents get it when they start, or
• tell the orchestrator to read it: beswarm skill system prints it.

Start the orchestrator

beswarm agent start --name lead --agent claude --group lead \
  --prompt "Run 'beswarm skill system' and follow it. Then: split adding OpenAPI docs to every route in src/routes into independent chunks. Start one named sub-agent per chunk in its own worktree, in group 'docs'. Wait for them, review each diff, and write a summary to reports/openapi.md. Don't merge anything."

Give it limits in the prompt: how many sub-agents at most, which agent kinds to use, and what it must not do (merge, push, remove worktrees).

Watch the tree

Agents the orchestrator starts from its own terminal are nested under it in the Agents panel. Click ▼ / ▲ after its status to show or fold them away.

From a shell:

beswarm agent list
beswarm agent wait lead --until done,blocked --timeout 7200

Permission prompts are yours

Sub-agents can block on permission prompts too. The orchestrator can see them, but approving a permission is your call. Tell it to stop and report instead of answering with send-keys:

If any sub-agent is blocked on a permission prompt, don't answer it. Stop and tell me which one and what it asks.

Shut it all down

Right-click the orchestrator in the Agents panel and choose Close. Its tab and every agent nested under it close together; the confirmation says how many. From the CLI:

beswarm agent close --group docs
beswarm agent close --group lead