Documentation \u2014 v7.0.1

Complete Reference

Everything you need to know about OpenCode Swarm \u2014 17 agents, council deliberation, mutation testing, code graph, and 6,000+ tests.

Overview

OpenCode Swarm is an OpenCode plugin that turns a single AI coding agent into a team of seventeen specialized agents with a rigorous QA pipeline. The philosophy: coordinating agents is solved \u2014 verifying their output isn't.

v7.0 added 8 new agents, council-based deliberation, code graph awareness, mutation testing, process reward modeling, write authority enforcement, and transient error recovery \u2014 all while maintaining the core principle: one task at a time, full QA pipeline before the next begins.

Agents

6,000+

Plugin Tests

15+

QA Gates/Task

150+

Releases to v7

The 17 Agents

Nine original agents handle the core pipeline. Eight new agents fill specific gaps that kept causing QA failures. Each has its own permission boundary \u2014 no one touches what they shouldn't.

Original Core Agents

Agent	Role	When
`@architect`	Plans the project, delegates tasks, enforces quality gates	Always (coordinator)
`@explorer`	Scans your codebase to understand what exists	Before planning, after each phase
`@sme`	Domain expert (security, APIs, databases, etc.)	During planning, guidance cached
`@critic`	Reviews the plan before any code is written	After planning, before execution
`@coder`	Writes code, one task at a time	During execution
`@reviewer`	Reviews code for correctness and security	After every task
`@test_engineer`	Writes and runs tests, including adversarial edge cases	After every task
`@designer`	Generates UI scaffolds and design tokens (opt-in)	Before UI tasks
`@docs`	Updates documentation to match what was built	After each phase

NEW IN v7Additional Agents

Agent	Role	When
`@hallucination_verifier`	Checks API calls against real sources to catch hallucinated endpoints	During execution
`@drift_verifier`	Catches spec divergence before it compounds across tasks	During execution
`@sounding_board`	Pushes back on decisions before they escalate to formal review	During planning
`@curator`	Consolidates knowledge across phases, deduplicates, quarantines low-quality entries	After each phase
`@council_advocate`	First member of the two-agent council for deliberation-based planning	During council deliberation
`@council_challenger`	Second member — challenges the advocate's position with adversarial analysis	During council deliberation
`@council_moderator`	Optional moderator that synthesizes council deliberation results	After council rounds
`@prm_scorer`	Process Reward Model — scores mid-execution trajectories to catch drift early	During execution

Architect Workflow Modes

The architect follows these modes in order. v7 adds council deliberation during planning, sounding board review, phase-level council, and optional mutation testing gates.

RESUME

Checks if .swarm/plan.md exists, picks up where it left off

SPECIFY

Generates a feature specification with requirements and acceptance criteria

CLARIFY

Asks you questions (only what it can't infer)

DISCOVER

Explorer scans the codebase + code graph builds

CONSULT

SME agents provide domain guidance, optionally convene council

PLAN

Architect writes the phased plan with council deliberation

CRITIC-GATE

Sounding board + critic review the plan (max 2 revision cycles)

EXECUTE

Tasks implemented one at a time through QA pipeline with PRM scoring

PHASE-COUNCIL

Phase-level council review fires at phase_complete (separate from per-task gates)

MUTATION-GATE

Optional: mutation testing validates test coverage for changed files

PHASE-WRAP

Docs update, retrospective written, curator consolidates knowledge

Execution Pipeline

Every single task goes through this pipeline. Stage B (reviewer + test engineer) always runs per-task. Council review is now a separate layer at phase_complete.

@coder implements (ONE task only, with code graph context)

Write authority check (permission boundary enforcement)

diff + imports (contract + dependency analysis)

syntax_check (parse validation)

placeholder_scan (catches TODOs, stubs)

lint fix → lint check

build_check (does it compile?)

pre_check_batch (lint, secretscan, SAST, quality)

@hallucination_verifier (API calls vs real sources)

@drift_verifier (spec divergence check)

PRM trajectory scoring (mid-execution correction)

@reviewer (correctness pass, different model)

@reviewer (security pass, if needed)

@test_engineer (verification tests + coverage ≥70%)

@test_engineer (adversarial tests)

post_check_batch (final lint, security, quality)

Evidence serialized to .swarm/

v7 fix: In earlier versions, enabling council_mode replaced per-task Stage B gates. v7 fixes this. Stage B always runs per-task. Council review is a separate full-phase review that fires at phase_complete. The two systems no longer interfere.

Council System

Two distinct council modes, each serving a different purpose.

Phase-Level Council

Fires at phase_complete. Full-phase review separate from per-task gates.

REJECT blocks phase completion
CONCERNS blocks unless configured otherwise
Runs after per-task Stage B gates, never replaces them

General Council

Invoked with /swarm council <question>. For architectural decisions.

Configurable multi-model panel
Each member gets independent web search
One deliberation round, optional moderator synthesis
Based on N-Way Self-Evaluating Deliberation (arXiv:2601.16863)

Code Graph

Agents now have structural awareness of your codebase.

How It Works

Repo graph builds at session start
Updates incrementally on file writes
Import parsing across TypeScript, JavaScript, Python
Symbol extraction for function/class awareness
Coder and reviewer get it injected automatically

Persistence

# Stored at

.swarm/repo-graph.json

# Survives

Session restarts

Process interruptions

# Updates

Incremental (no full rebuilds)

Before code graph, agents read around the codebase effectively blind. Now they understand the import/dependency structure before writing a single line.

Knowledge System

A two-tier architecture with a dedicated curator agent. Lessons flow from project-level to organization-level.

Swarm-Level

.swarm/knowledge.jsonl

\u2022 Max 100 entries per project
\u2022 Retrospectives capture lessons after each phase
\u2022 Confidence & utility scoring
\u2022 Project-specific context

Hive-Level

~/.config/opencode/hive-knowledge.jsonl

\u2022 Max 1,000 entries across all projects
\u2022 Auto-promotes from swarm after 30 days
\u2022 Smart injection into new projects
\u2022 Deduplication, quarantine, auto-pruning

How Knowledge Flows

Capture

Retrospectives after each phase capture lessons with structured metadata

Score

Each lesson gets confidence & utility scores based on evidence

Curate

Dedicated curator agent consolidates, deduplicates, quarantines low-quality entries

Promote

High-confidence lessons auto-promote to hive-level after 30 days

Inject

Relevant hive knowledge injected into new projects automatically

Mutation Testing Gate

Optional gate (default off). When enabled, phase_complete blocks until the test suite has been validated against generated mutations for files changed in the phase.

Why It Matters

Closes the gap between "tests pass" and "tests actually cover the behavior that changed." Most test suites can't answer this question.

Generates mutations for changed files
Validates test suite catches the mutations
FAIL blocks phase completion
WARN proceeds with warning

Configuration

// In swarm config

{

"mutation_testing": {

"enabled": true,

"fail_action": "FAIL"

}

Opt-in because it's expensive, but for high-stakes feature work it's essential.

Security & Guardrails

Write Authority Enforcement

\u2022 Every write call authority-checked before execution
\u2022 Symlink traversal blocked (no src/ \u2192 /etc/ exploit)
\u2022 Universal deny: .env, secrets/, .git/config
\u2022 Per-agent permission boundaries enforced

Built-In Security Pipeline

\u2022 Offline SAST scanning
\u2022 Secret detection
\u2022 Security-focused code review pass
\u2022 pre_check_batch + post_check_batch gates

Runtime Guardrails

max_tool_calls

200

Per-task tool call limit

max_duration_minutes

Per-task time limit

max_retries

Per-task retries on failure

circuit_breaker

Total errors before stopping (logic failures)

transient_retry_budget

Separate budget for 429/503 errors (resets per call)

min_coverage

70%

Minimum test coverage requirement

Transient error recovery (v7): Rate limits (429) and service unavailable (503) errors get a separate retry budget that doesn't touch the circuit breaker. Infrastructure outages during long sessions no longer kill the run.

Persistent State

Everything lives in .swarm/. Close your laptop, come back next week \u2014 pick up exactly where you left off.

.swarm/

\u251c\u2500\u2500 plan.md # The full project plan

\u251c\u2500\u2500 state.json # Current phase, task, completion status

\u251c\u2500\u2500 knowledge.jsonl # Project-level lessons

\u251c\u2500\u2500 repo-graph.json # Code graph (NEW v7)

\u251c\u2500\u2500 evidence/ # Every task, gate, review serialized

\u251c\u2500\u2500 checkpoints/ # Resumable state snapshots

\u251c\u2500\u2500 retrospectives/ # Phase retrospectives

\u2514\u2500\u2500 sme-cache/ # Cached SME guidance

Supported Languages

Tier 1 \u2014 Full Support

Syntax, lint, build, test, security

\u2022 TypeScript
\u2022 JavaScript
\u2022 Python
\u2022 Go
\u2022 Rust

Tier 2 \u2014 Good Support

Syntax, lint, partial build/test

\u2022 Java
\u2022 C#
\u2022 Ruby

Tier 3 \u2014 Basic

Syntax check only

\u2022 PHP
\u2022 Swift
\u2022 Kotlin

All Commands

NEWv7 Commands

/swarm pr-review <url|shorthand>

PR review with 6 parallel lanes, reviewer + critic. --council for adversarial mode.

/swarm issue <url|shorthand>

Issue analysis: symptoms, fault localization, fix spec. --trace for full fix. --no-repro to skip repro.

/swarm council <question>

Multi-model deliberation panel with web search and synthesis.

Core Commands

Command	Description
`/swarm`	Start the swarm workflow
`/swarm status`	Current phase & task progress
`/swarm plan`	Show the full project plan
`/swarm approve`	Approve the plan and begin execution
`/swarm reject [reason]`	Reject plan with feedback
`/swarm evidence <task_id>`	Show gate results for a task
`/swarm history`	Completed work summary
`/swarm diagnose`	Health check for swarm state
`/swarm retry`	Retry the current failed task
`/swarm skip`	Skip current task (use sparingly)
`/swarm pause`	Pause execution
`/swarm resume`	Resume from pause
`/swarm reset --confirm`	Clear all state and start over
`/swarm config`	Show current configuration
`/swarm knowledge`	View knowledge base
`/swarm knowledge promote <id>`	Promote to hive-level
`/swarm knowledge quarantine <id>`	Quarantine a lesson
`/swarm knowledge stats`	Knowledge system statistics
`/swarm export`	Export plan and evidence
`/swarm metrics`	Time, tokens, pass/fail rates

Configuration

Configuration lives in .opencode/swarm.json (project) or ~/.config/opencode/opencode-swarm.json (global).

{
  "agents": {
    "architect": { "model": "anthropic/claude-opus-4-6" },
    "coder":     { "model": "minimax-coding-plan/MiniMax-M2.5" },
    "reviewer":  { "model": "zai-coding-plan/glm-5" }
  },
  "guardrails": {
    "max_tool_calls": 200,
    "max_duration_minutes": 30,
    "min_coverage": 70
  },
  "council_mode": "phase_complete",
  "mutation_testing": {
    "enabled": false,
    "fail_action": "FAIL"
  },
  "code_graph": {
    "enabled": true,
    "languages": ["typescript", "javascript", "python"]
  }
}

Want to Dive Deeper?

Check the full source, architecture docs, and design rationale on GitHub.

View on GitHub