Scripted swarm

Drive BeSwarm from a shell script, a CI job or an orchestrating agent. --json, --wait and the exit codes are built for it.

Exit codes

A fan-out script

Start one agent per package, wait for each, and stop on the first failure:

#!/usr/bin/env bash
set -euo pipefail
 
for pkg in core cli web; do
  beswarm agent start --name "lint-$pkg" --agent codex --group lint --no-focus \
    --prompt "Fix lint errors in packages/$pkg. Run the linter before you finish."
done
 
for pkg in core cli web; do
  beswarm agent wait "lint-$pkg" --until done,blocked --timeout 1800
done
 
beswarm agent list --json

--no-focus keeps new tabs from stealing focus while you work.

Branch on status

agent get --json returns the full result for one agent, so a script can branch on it:

beswarm agent get lint-core --json

A blocked agent needs a decision. Read its screen with agent read --source visible before answering with agent send-keys.

Rules for scripts

• Name every agent and address it by name or terminal id, never by kind.
• Parse ids and names from status, agent list and workspace list output.
• A wait timeout doesn't prove the prompt was never delivered — don't blindly resend it.
• Never add --yes or --force just to get past a refusal.

The full list is in Safety rules.