Documentation

Everything You Need to Know

Comprehensive documentation for OpenCode Swarm — from quick start to advanced configuration.

Overview

OpenCode Swarm is a plugin for OpenCode that turns a single AI coding agent into a team of nine. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another catches security issues. Nothing ships until every check passes.

9 Specialized Agents

Each with a distinct role

7 Quality Gates

Every task validated

Persistent State

Resume anytime

The Agents

Swarm has nine agents. You don't interact with them directly — the architect orchestrates everything.

Agent	Role	When It Runs
`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

Architect Workflow Modes

The architect moves through these modes automatically:

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

CONSULT

SME agents provide domain guidance

PLAN

Architect writes the phased plan

CRITIC-GATE

Critic reviews the plan (max 2 revision cycles)

EXECUTE

Tasks implemented one at a time through QA pipeline

PHASE-WRAP

Phase completes, docs update, retrospective written

Execution Pipeline

Every task goes through this sequence. No exceptions, no overrides.

@coder implements (ONE task only)

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)

@reviewer (correctness pass)

@reviewer (security pass, if needed)

@test_engineer (verification tests + coverage ≥70%)

@test_engineer (adversarial tests)

Pre-commit checklist (all 4 items required)

Task marked complete, evidence written

If any step fails, the coder gets structured feedback and retries. After 3 failures, the architect consults the critic. After 5 total failures, it escalates to you.

Persistent Memory (.swarm/)

All state lives in a .swarm/ folder in your project:

plan.md

Your project roadmap (tasks, status, what's done, what's next)

plan.json

Machine-readable plan state

context.md

Decisions made, expert guidance, established patterns

spec.md

Feature specification (requirements, acceptance criteria)

knowledge.jsonl

Cross-project knowledge base (lessons, patterns)

events.jsonl

Structured event log (delegations, gate results)

evidence/

Review verdicts, test results, diffs for every task

checkpoints/

Git state snapshots for rollback

history/

Phase retrospectives and metrics

Close your terminal. Come back next week. Swarm reads these files and picks up exactly where it stopped.

Knowledge System

Swarm doesn't just complete tasks — it learns from every project and shares that wisdom across all your work. This is the secret sauce that makes Swarm get smarter over time.

Two-Tier Knowledge Architecture

Swarm-Level

.swarm/knowledge.jsonl

Project-specific lessons

Max 100 entries per project

Auto-Promote

High confidence

Hive-Level

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

Cross-project wisdom

Max 1000 entries globally

How Knowledge Flows

Retrospectives Capture Lessons

After each phase completes, Swarm runs a retrospective that identifies what worked, what failed, and why. These lessons are written to the swarm-level knowledge base.

Confidence & Utility Scoring

Each knowledge entry gets a confidence score (how reliable is this lesson?) and a utility score (how often is it retrieved and helpful?). Both scores update over time based on real usage.

Automatic Promotion to Hive

After 30 days, entries with high confidence (≥0.8) and high utility (≥0.5) are automatically promoted to the hive-level knowledge base, making them available to ALL your swarms.

Injection Into Future Projects

When a new swarm starts, relevant hive knowledge is injected into the context. The architect and other agents benefit from lessons learned across all your previous projects.

Automatic Knowledge Curation

Deduplication

Cosine similarity threshold of 0.6 prevents duplicate lessons from being stored.

Quarantine System

Bad rules can be retracted via retrospectives or manually quarantined. Fingerprinted to prevent re-learning.

Auto-Pruning

Low-utility entries (utility < 0.2) with minimal retrievals are automatically removed.

Knowledge Commands

/swarm knowledge quarantine <id> [reason]Manually quarantine a bad or misleading knowledge entry

/swarm knowledge restore <id>Restore a previously quarantined entry

/swarm knowledge migrateMigrate legacy lessons from context.md to knowledge.jsonl

Knowledge Configuration

{
  "knowledge": {
    "enabled": true,
    "swarm_max_entries": 100,
    "hive_max_entries": 1000,
    "auto_promote_days": 30,
    "max_inject_count": 5,
    "dedup_threshold": 0.6,
    "hive_enabled": true,
    "evergreen_confidence": 0.8,
    "evergreen_utility": 0.5,
    "low_utility_threshold": 0.2
  }
}

Why This Matters

Most AI coding tools start from scratch every session. Swarm builds institutional memory. That mistake you made on Project A? Swarm won't let you make it again on Project B. That clever pattern you discovered? It's now available to every project you start. The more you use Swarm, the smarter it gets.

Guardrails & Circuit Breakers

Every agent runs inside a circuit breaker that kills runaway behavior before it burns your credits.

Signal	Default Limit	What Happens
Tool calls	`200`	Agent is stopped
Duration	`30 min`	Agent is stopped
Same tool repeated	`10x`	Agent warned, then stopped
Consecutive errors	`5`	Agent is stopped

Limits reset per task. Override per-agent in your config.

Supported Languages

OpenCode Swarm v6.16+ ships with language profiles for 11 languages across three quality tiers.

Language	Tier	Lint	Test	SAST
TypeScript / JavaScript	1	Biome / ESLint	✓	Semgrep
Python	1	ruff	pytest	Semgrep
Rust	1	clippy	cargo test	Semgrep
Go	1	golangci-lint	go test	Semgrep
Java	2	Checkstyle	JUnit	Semgrep
Kotlin	2	ktlint	JUnit	Semgrep beta
C# / .NET	2	dotnet format	dotnet test	Semgrep
C / C++	2	cppcheck	ctest	Semgrep exp.
Swift	2	swiftlint	swift test	Semgrep exp.
Dart / Flutter	3	dart analyze	dart test	—
Ruby	3	RuboCop	RSpec/minitest	Semgrep exp.

Tier 1: Full pipeline. Tier 2: Strong coverage. Tier 3: Basic coverage.

Configuration

Config file location: ~/.config/opencode/opencode-swarm.json (global) or .opencode/swarm.json (project). Project config merges over 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
  },
  "knowledge": {
    "enabled": true,
    "hive_enabled": true
  }
}

All Commands

Complete list of slash commands available in OpenCode Swarm.

/swarm statusCurrent phase, task progress, agent count

/swarm plan [N]Full plan or filtered by phase

/swarm agentsRegistered agents with models and permissions

/swarm historyCompleted phases with status

/swarm configCurrent resolved configuration

/swarm config doctor [--fix]Config validation with optional auto-fix

/swarm diagnoseHealth check for .swarm/ files and config

/swarm exportExport plan and context as portable JSON

/swarm evidence [task]Evidence bundles for a task or all tasks

/swarm archive [--dry-run]Archive old evidence with retention policy

/swarm retrieve [id]Retrieve auto-summarized tool outputs

/swarm reset --confirmClear swarm state files

/swarm specify [description]Generate or import a feature specification

/swarm clarify [topic]Clarify and refine an existing specification

/swarm analyzeAnalyze spec.md vs plan.md for coverage gaps

/swarm preflightRun phase preflight checks

/swarm sync-planForce plan.md regeneration from plan.json

/swarm benchmarkPerformance benchmarks

/swarm dark-matterDetect hidden file couplings via git analysis

/swarm knowledge quarantine <id>Quarantine a knowledge entry

/swarm knowledge restore <id>Restore a quarantined entry

/swarm knowledge migrateMigrate legacy context.md to knowledge.jsonl

/swarm rollbackRestore swarm state to a checkpoint