All /swarm subcommands available in OpenCode Swarm v6.81.0. The authoritative source is src/commands/registry.ts.
Commands are grouped by function. Compound commands (e.g., /swarm config doctor) resolve the two-word form first, then fall back to the first token.
Several swarm subcommands share exact names with Claude Code built-in slash commands. This is a known source of model confusion — AI agents trained on Claude Code may try to invoke the CC built-in instead of the swarm subcommand.
All swarm commands must use the full /swarm <subcommand> form. Never reference a
conflicting swarm subcommand by its bare name when inside a swarm agent context.
| Swarm Command | Conflicts With | Severity | CC Behavior |
|---|---|---|---|
/swarm plan |
/plan |
🔴 CRITICAL | Enters plan mode — Claude proposes before executing |
/swarm reset |
/reset |
🔴 CRITICAL | Alias for /clear — wipes entire conversation |
/swarm checkpoint |
/checkpoint |
🔴 CRITICAL | Alias for /rewind — restores prior conversation state |
/swarm status |
/status |
🟠 HIGH | Shows Claude version, model, account info |
/swarm agents |
/agents |
🟠 HIGH | Manages Claude subagent configurations |
/swarm config |
/config |
🟠 HIGH | Opens Claude Code settings interface |
/swarm export |
/export |
🟠 HIGH | Exports conversation as plain text |
/swarm config doctor |
/doctor |
🟠 HIGH | Diagnoses Claude Code installation |
/swarm history |
/history |
🟡 MEDIUM | Shows Claude Code session history |
For contributors: Adding a new swarm command that matches a CC built-in requires
updating src/commands/conflict-registry.ts with an explicit severity and
disambiguation note. The CI test in src/commands/conflict-registry.test.ts will
fail until this is done.
Show current swarm state: active phase, task count, and registered agents.
Phase: 2 [IN PROGRESS]
Tasks: 3/5 complete
Agents: 11 registered
Run a health check on .swarm/ files, plan structure, and evidence completeness. Reports missing files, schema mismatches, and recovery steps.
Show completed phases with status icons.
/swarm history
List all registered agents with their model, temperature, read-only status, and guardrail profile.
Display the full .swarm/plan.md. With a phase number, show only that phase.
/swarm plan # full plan
/swarm plan 2 # Phase 2 tasks only
Generate or import a feature specification from prose. Writes .swarm/spec.md using RFC 2119 keywords (MUST / SHOULD / MAY).
Refine an existing spec.md by clarifying ambiguous requirements.
Compare spec.md against plan.md to find requirement coverage gaps. Useful before running a phase — identifies requirements not covered by any task.
Enter architect BRAINSTORM mode: seven-phase planning workflow for new features needing requirement discovery. Sequence: CONTEXT SCAN → DIALOGUE → APPROACHES → DESIGN → SPEC → SELF-REVIEW → GATE SELECTION → TRANSITION.
Enter architect MODE: COUNCIL — convene a configurable multi-model General Council for an advisory deliberation. Each council member independently web-searches and answers; the architect routes any disagreements back for one targeted reconciliation round; an optional moderator pass synthesizes the final user-facing answer.
| Flag | Effect |
|---|---|
--preset <name> |
Use a named member group from council.general.presets instead of council.general.members. Preset name must match [A-Za-z0-9_-]{1,64}. |
--spec-review |
Switch to single-pass advisory mode. Used by the council_general_review QA gate during MODE: SPECIFY to fold council input into a draft spec — no Round 2 deliberation. |
Prerequisites: council.general.enabled: true and a configured search API key (Tavily or Brave) in opencode-swarm.json. See Council guide — General Council Mode for setup.
No-args behavior: prints a usage string. The command never throws on bad input — invalid preset names and injected [MODE: ...] headers are silently dropped.
Launch a structured deep PR review using multi-lane parallel analysis with independent confirmation and critic challenge.
| Argument | Description |
|---|---|
<pr-url> |
Full GitHub PR URL (e.g., https://github.com/owner/repo/pull/42) |
owner/repo#N |
Shorthand format — resolves owner and repo from the reference |
N |
Bare PR number — resolves owner and repo from the git remote origin |
--council |
Enable adversarial multi-model council review variant |
URL sanitization: Enforces https-only scheme, blocks localhost/private IPs, strips credentials and query strings, enforces max 2048 characters, rejects non-ASCII hostnames.
Workflow:
- Intent Reconstruction — Extract obligations from PR body checkboxes, linked issues, commit scopes, test names, and interface changes
- Parallel Explorer Lanes — 6 lanes: correctness, security, dependencies, docs-vs-intent, tests, performance/architecture
- Independent Reviewer Confirmation — Validate each finding with file:line evidence
- Critic Challenge — Adversarial review of HIGH/CRITICAL findings only
- Synthesis — Obligation assessment, findings table, merge recommendation
Council variant (--council): After standard review, convene a General Council to evaluate review quality and hunt for blind spots. Council findings are supplementary.
No-args behavior: prints a usage string. The command never throws on bad input.
Ingest a GitHub issue into the swarm workflow for root-cause localization and resolution spec generation.
| Argument | Description |
|---|---|
<issue-url> |
Full GitHub issue URL (e.g., https://github.com/owner/repo/issues/42) |
owner/repo#N |
Shorthand format — resolves owner and repo from the reference |
N |
Bare issue number — resolves owner and repo from the git remote origin |
--plan |
Transition to plan creation after spec generation |
--trace |
Run full fix-and-PR workflow (implies --plan) |
--no-repro |
Skip reproduction verification step |
URL sanitization: Enforces https-only scheme, blocks localhost/private IPs, strips credentials and query strings, enforces max 2048 characters, rejects non-ASCII hostnames.
Workflow:
- Intake — Fetch issue body via GitHub CLI, normalize into structured intake note (observed behavior, expected behavior, repro steps, environment)
- Localization — Build 2–5 root-cause hypotheses with composite scoring (stack-trace 0.4, recency 0.25, call-graph 0.2, test-failure 0.15), validate top-3 in parallel, prune to single root cause
- Spec Generation — Output resolution spec with root cause, fix strategy, FR/SC numbering, Given/When/Then scenarios
- Transition — Based on flags: report spec (
no flags), create plan (--plan), or run full fix workflow (--trace)
Flag interactions: --trace implies --plan. Both flags can be combined with --no-repro.
No-args behavior: prints a usage string. The command never throws on bad input.
Output signal: Successful execution emits [MODE: ISSUE_INGEST issue="<sanitized-url>" plan=true trace=true noRepro=true] with only the flags that were set.
Force plan.md regeneration from canonical plan-ledger.jsonl. Safe, read-only.
Run preflight automation checks before starting a phase. Validates plan completeness, evidence requirements, and blockers.
Toggle Turbo Mode for the current session. Skips non-critical QA gates for faster iteration. Session-scoped; resets on new session.
/swarm turbo # toggle
/swarm turbo on # enable
/swarm turbo off # disable
See Modes Guide for tradeoffs.
Toggle Full-Auto Mode. Enables autonomous execution without confirmation prompts. Session-scoped.
Show the current resolved plugin configuration (merged global + project + CLI overrides).
Run config validation and integrity checks. Alias: /swarm config-doctor (hyphenated form for TUI shortcut compatibility).
--fix: auto-repair issues where safe. Creates encrypted backup first.--restore <id>: revert to a previous backup.
Run tool registration coherence check. Verifies all tools declared in the registry are available at runtime.
View or modify QA gate profile for the current plan.
show: display spec-level, session-override, and effective gates.enable: persist gate(s) into the locked profile. Architect-only. Rejected after critic approval lock.override: session-only ratchet-tighter enable.
Valid gates: reviewer, test_engineer, council_mode, sme_enabled, critic_pre_plan, hallucination_guard, sast_enabled, mutation_test, council_general_review.
Gate descriptions:
council_mode— Multi-member phase-level council gate. When enabled, council runs at phase completion for holistic review of the full phase body of work. Stage B (reviewer + test_engineer in parallel) always runs per-task regardless. Council is additive — never replaces Stage B.
Show evidence bundles (review results, test verdicts, security findings) for a task. Without taskId, lists all tasks with evidence.
/swarm evidence 2.1
Generate an evidence summary showing completion ratio across all tasks, blockers, and missing evidence. Alias: /swarm evidence-summary.
Archive old evidence bundles. Two-tier retention: age-based (max_age_days, default 90) then count-based (max_bundles, default 1000). Use --dry-run to preview.
Show performance metrics: tool call rates, delegation chains, evidence pass rates.
--cumulative: aggregate across sessions.--ci-gate: return non-zero exit if thresholds exceeded (for CI).
Load the full tool output that was previously summarized (IDs like S1, S2). Use when the summary is insufficient and you need the raw data.
List knowledge entries in .swarm/knowledge.jsonl. Filter by category, confidence, or utility.
One-time migration from legacy .swarm/context.md SME cache to .swarm/knowledge.jsonl. Idempotent — skips if already migrated.
Move a knowledge entry to quarantine. Quarantined entries are excluded from agent queries.
Restore a quarantined entry back to active knowledge.
Manually promote a lesson to hive (cross-project) knowledge. Either pass lesson text directly or reference an existing swarm-level lesson by ID.
Run knowledge curation and review hive promotion candidates. Identifies evergreen lessons for cross-project reuse.
DELETE plan.md, context.md, and summaries/ from .swarm/. Stops background automation and clears in-memory queues. Requires --confirm — without it, shows a warning and a tip to export first.
Clear only session state (.swarm/session/state.json and related files). Preserves plan, evidence, and knowledge. Use when starting a new model/session but continuing the same project.
Named snapshots of .swarm/ state.
save <label>: create snapshot.restore <label>: soft-reset to checkpoint.delete <label>: remove checkpoint.list: show all checkpoints.
Restore .swarm/ to a phase checkpoint (checkpoints/phase-<N>). Writes a rollback event to events.jsonl. Without a phase argument, lists available checkpoints.
Idempotent 4-stage project finalization:
- Finalize — write retrospectives for in-progress phases.
- Archive — timestamped bundle of swarm artifacts and evidence.
- Clean — remove active-state files.
- Align — safe git
ff-onlytomain.
Reads .swarm/close-lessons.md for explicit lessons and runs curation.
Prepare state for a clean model switch. Writes handoff.md with full session state snapshot (plan progress, decisions, delegation history) for prepending to the next session.
Export the current plan and context as JSON to stdout. Useful for piping to external tools or debugging.
Write a retrospective evidence bundle for a completed phase. Required JSON fields: phase, summary, task_count, task_complexity, total_tool_calls, coder_revisions, reviewer_rejections, test_failures, security_findings, integration_issues. Optional: lessons_learned (max 5), top_rejection_reasons, task_id, metadata.
Output: .swarm/evidence/retro-{phase}/evidence.json.
Detect hidden file couplings via co-change NPMI (Normalized Pointwise Mutual Information) analysis of git history. Finds files that change together but aren't obviously related in code.
Dry-run the dark-matter analysis with configurable thresholds. Does not modify state.
Acknowledge that the spec has drifted from the plan and suppress further warnings. Use after you've reviewed the drift and accepted it.
When you type a two-word command like /swarm config doctor, Swarm tries the compound key first, then falls back to the single-token key. Aliases with hyphens exist for TUI shortcuts (which split on hyphens):
| Command | Alias |
|---|---|
/swarm config doctor |
/swarm config-doctor |
/swarm evidence summary |
/swarm evidence-summary |
Nine swarm commands share names with Claude Code built-in slash commands. Using the bare CC command instead of /swarm <command> has different — sometimes destructive — behavior. Swarm shows a src/commands/conflict-registry.test.ts) prevents new CRITICAL conflicts from being added without explicit acknowledgment.
| Swarm Command | CC Built-in | Severity | CC Behavior | Swarm Behavior |
|---|---|---|---|---|
/swarm plan |
/plan |
CRITICAL | Enters Claude Code plan mode — Claude proposes all actions before executing | Displays the current .swarm/plan.md task list |
/swarm reset |
/reset |
CRITICAL | Alias for /clear — wipes the entire conversation context window |
Clears .swarm state files (requires --confirm flag) |
/swarm checkpoint |
/checkpoint |
CRITICAL | Alias for /rewind — restores conversation and code to a prior state |
Manages named swarm project snapshots (save|restore|delete|list) |
/swarm status |
/status |
HIGH | Shows CC version, model, account, and API connectivity | Shows current swarm state: active phase, task counts, registered agents |
/swarm agents |
/agents |
HIGH | Manages Claude Code subagent configurations and teams | Lists registered swarm plugin agents with model, temperature, and guardrail info |
/swarm config |
/config |
HIGH | Opens Claude Code settings interface | Shows the current resolved opencode-swarm plugin configuration |
/swarm export |
/export |
HIGH | Exports the current CC conversation as plain text to a file | Exports the swarm plan and context as JSON to stdout |
/swarm doctor |
/doctor |
HIGH | Diagnoses the CC installation (version, auth, permissions) | Runs health checks on swarm configuration and state files |
/swarm history |
/history |
MEDIUM | Shows CC session history | Shows completed swarm phases with status icons |
| Level | Meaning |
|---|---|
| CRITICAL | Bare CC invocation causes destructive behavior (context wipe, conversation rewind, plan mode block). Always use /swarm. |
| HIGH | CC invocation does something unrelated to swarm. Confusing but recoverable. |
| MEDIUM | CC invocation does something tangentially related. Low risk of confusion. |
src/commands/conflict-registry.test.ts enforces a hard gate: new CRITICAL conflict entries fail the test suite unless the entry is added to an explicit allow-list array in the test. This prevents accidental CRITICAL conflicts from being merged without review.
Type /swarm <subcommand> in the chat. All commands in this reference work here.
The standalone binary accepts three top-level commands: install, uninstall, and run. To invoke a registry command from the shell, prefix it with run:
opencode-swarm run status
opencode-swarm run plan 2
opencode-swarm run evidence 2.1Session-scoped commands (turbo, full-auto) require an active session and only work inside an OpenCode session — invoking them via the standalone CLI will fail.
Both routes share the same registry. See src/commands/registry.ts for the raw definitions and src/cli/index.ts for the standalone dispatcher.
- Getting Started — first-run walkthrough
- Modes Guide — Balanced vs Turbo vs Full-Auto tradeoffs
- Configuration Reference — all config keys
- Knowledge System — hive vs swarm knowledge
- Evidence and Telemetry — observability