13 -Reference

Command reference

Commands, flags, resolution modes, presets, and the artifacts every run writes to disk.

Commands

Usage: agent-swarm [options] [command]

Commands:
  run [options] <rounds> <topic...>  Run a swarm
  doctor                             Diagnose swarm setup
  init [options]                     Create .agent-swarm/config.yml defaults
  help [command]                     Display help for a command

Running agent-swarm with no arguments prints this top-level help and exits 0, the same as agent-swarm --help.

`agent-swarm run`

Usage: agent-swarm run [options] <rounds> <topic...>

Arguments:
  rounds             number of rounds (1-3)
  topic              topic for the swarm

Options:
  --agents <list>    comma-separated agent names (2-5)
  --backend <name>   runtime backend adapter (claude, codex)
  --resolve <mode>   between-round resolution: off | orchestrator | agents
  --goal <text>      primary goal for the swarm
  --decision <text>  decision target for the swarm
  --doc <path>       carry-forward document (repeatable)
  --preset <name>    named preset (used when --agents is not provided)
  --timeout-ms <ms>  per-agent and orchestrator dispatch timeout (default: 120000)
  --quiet            force quiet output; default auto by TTY

Resolution modes

--resolve controls what happens between rounds while the run is in flight.

Mode	Between-round behavior
`off`	Deterministic only - the next-round brief gets a templated summary built from the prior packet. No extra LLM call.
`orchestrator`	Real LLM pass - the bundled `orchestrator` agent reads the prior packet and returns a structured `OrchestratorOutput` that feeds the next round. Each pass is captured in `checkpoint.json` as inspectable recovery state; user-facing resume tooling is future work.
`agents`	Reserved - accepted and persisted but currently behaves like `off`.

`agent-swarm doctor`

agent-swarm doctor validates your setup before a run. Output is grouped into three sections:

Configuration - config parses cleanly, carry-forward docs are readable, the agent and preset registries load, referenced agents and presets resolve, and the configured --backend is supported.
Harness inventory - all four harnesses (Claude, Codex, OpenCode, Rovo) are probed for availability and auth, even with no project config. A harness that fails but is not required by your configured agents is reported as WARN (non-fatal). A failing harness required by one or more agents is FAIL with required by: <agent...> attribution and guidance. agent-swarm does not globally require any harness; a single-harness setup passes doctor when its required harness works.
Agent summary - each configured agent mapped to its resolved harness. With no project config, the default product-triad preset's agents are shown.

Exit codes: 0 ready, 1 a check failed, 2 internal error.

`agent-swarm init`

Usage: agent-swarm init [options]

Options:
  --force  overwrite an existing .agent-swarm/config.yml

agent-swarm init writes minimal safe defaults to .agent-swarm/config.yml, leaves existing config unchanged unless --force is passed, and never mutates legacy .swarm/config.yml.

Bundled presets

Agent Swarm ships with seven bundled presets:

Preset	Agents	Description
`product-decision`	`product-manager`, `principal-engineer`	The supported alpha flow: framing a product decision through user-value and engineering-feasibility lenses.
`product-decision-codex`	`product-manager-codex`, `principal-engineer-codex`	The same flow, dispatched through Codex.
`product-decision-opencode`	`product-manager-opencode`, `principal-engineer-opencode`	The same flow, dispatched through OpenCode.
`triad`	`product-manager`, `principal-engineer`, `product-designer`	Full product triad: value, feasibility, and UX together.
`product-triad`	`product-manager`, `product-engineer`, `product-designer`	First-time default for product, design, and build tradeoffs.
`adversarial-code-review`	`code-reviewer`, `implementation-skeptic`, `test-risk-reviewer`	Proposed code changes, PR plans, and architecture diffs.
`customer-panel`	`first-time-user`, `busy-operator`, `skeptical-buyer`	First-run value, adoption blockers, and outside-in product feedback.

Select a preset with --preset, or pass explicit --agents. Run-level --backend chooses the default adapter; individual agents can still pin their own harness.

Run artifacts

Each run writes a self-contained directory under .agent-swarm/runs/<timestamp>-<slug>/:

manifest.json - run inputs and resolved runtimes.
checkpoint.json - append-only, inspectable recovery state for run progress.
events.jsonl / messages.jsonl - the run ledger.
round-NN/ - per-round brief and each agent's markdown output.
synthesis.json / synthesis.md - the deterministic final report.