Agent Swarmdocs
GitHub

02 -Start

From zero to a synthesized decision

Install the CLI, verify your harness setup, and run a one-round swarm with the bundled product-decision preset - no config required.

This page: install → doctor → run → read the synthesis

Prerequisites

  • Node ≥ 20 (Node 24 LTS recommended - .nvmrc pins it).
  • pnpm 10 for source installs and development.
  • A harness CLI on PATH, authenticated. The bundled product-decision preset uses Claude (claude auth login); other presets use Codex (codex login) or OpenCode (opencode auth login).

Install

Install the CLI globally - every method gives you the same agent-swarm command:

# npm
npm install -g @calvinnwq/agent-swarm

# pnpm
pnpm add -g @calvinnwq/agent-swarm

Prefer not to install a global CLI? Run any command on demand with npx -y @calvinnwq/agent-swarm in place of agent-swarm.

For agent-operated setup, install the public skill instead - it runs the CLI for you:

npx skills add calvinnwq/agent-swarm --skill agent-swarm

For source installs and development:

pnpm install
pnpm build
pnpm link --global

Verify your setup

Run agent-swarm doctor before your first swarm. It checks project config, configured docs, the agent and preset registries, and backend compatibility (Configuration section). It also probes all four harnesses for availability and auth regardless of whether a project config exists (Harness inventory section), and maps each configured agent to its resolved harness (Agent summary section). A harness that is missing or unauthenticated but not required by your config is a non-fatal WARN; one required by an agent is a FAIL. agent-swarm does not globally require any harness; a single-harness setup passes doctor when its required harness works. 

agent-swarm doctor

Doctor exits 0 when everything is ready, 1 when a check fails, and 2 on an internal error.

Run your first swarm

The first positional argument is the number of rounds (1-3); the rest is your question:

agent-swarm run 1 "Should we adopt server components?" \
  --preset product-decision \
  --goal "Decide on migration strategy" \
  --decision "Adopt / Defer / Reject" \
  --timeout-ms 300000
Note

Real harnesses can take longer than the default 120s dispatch timeout - bump --timeout-ms for deeper runs. Use --quiet for one-line-per-event output in CI.

Read the result

When it finishes, you'll find a self-contained run directory under .agent-swarm/runs/<timestamp>-<slug>/ with a deterministic synthesis.md. The synthesis combines the agents' answers into one call in the preset's own decision vocabulary:

Synthesisproduct-decision · round 1 · 2 agents

Proceed - server components fit the migration if routing is staged first.

consensus2 of 2 agree
confidencemedium
Still openDoes the data-fetching layer change before or after the routing migration?

Confidence is reported as a level - low, medium, or high - not a fabricated percentage, and the verdict word comes straight from the preset's --decision vocabulary.

Where next