Multi-agent runs

Coordinate several agents in one workspace.

You can run multiple agents against the same workspace when the work splits cleanly. Each agent gets its own run; the workspace serializes write access.

When to split

Good candidates:

Independent modules or packages
Research tasks that do not write files
Parallel test-fix loops on separate suites

Avoid splitting when agents would edit the same files — conflicts are surfaced, not merged.

Fan-out from the CLI

optamus run --parallel 3 "Fix the failing tests in packages/*/"

Fan-out from the API

curl -X POST https://api.optamus.cloud/v1/runs \
  -H "Authorization: Bearer $OPTAMUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Fix tests in contracts","workspace":"optamus-core"}'

Each run streams independently. Collect results and review diffs together before applying.