OpenCode Swarm

---

OpenCode Swarm is a plugin for OpenCode that turns a single AI coding session into an architect-led team of specialized core, optional, and conditional agents. Run /swarm agents for the live roster; it is generated from the current plugin configuration. One agent writes the code. A different agent reviews it. Another writes and runs tests. Another checks security. Nothing ships until every required gate passes.

bunx opencode-swarm install

This single command installs the package, registers it as an OpenCode plugin, disables conflicting default agents, and creates a ready-to-edit config at ~/.config/opencode/opencode-swarm.json. Requires Bun (bun --version to check). If you must use npm: npm install -g opencode-swarm && opencode-swarm install.

First-run note: the installer registers the plugin, writes the global plugin config, creates a project override when missing, and disables the native explore and general agents in opencode.json. If you are not using a Swarm architect, the Swarm gates, reviewers, and test agents are bypassed. Open the OpenCode agent or mode picker and choose the Swarm architect when needed.

Why Swarm?

Most AI coding tools let one model write code and ask that same model whether the code is good. That misses too much. Swarm separates planning, implementation, review, testing, and documentation into specialized internal roles — and enforces gated execution so agents never mutate the codebase in parallel.

Key Features

• 🏗️ Specialized core, optional, and conditional agents — architect, coder, reviewer, test_engineer, critic, critic_finding_validator, explorer, sme, docs, designer, critic_oversight, critic_sounding_board, critic_drift_verifier, critic_hallucination_verifier, curator_init, curator_phase, council_generalist, council_skeptic, council_domain_expert. Run /swarm agents for the live roster — that is the source of truth, not this list.
• 🔒 Gated pipeline — code never ships without reviewer + test engineer approval
• 🔎 Independent auto-review engine — bounded whole-diff review in a fresh read-only model session, structured diff-anchored findings, optional independent validation, advisory-by-default phase review, and an evidence-backed opt-in completion gate. v7 remains opt-in; v8’s default is pinned to a committed 30-diff cost burn-in.
• 🔍 DEEP_DIVE Protocol — High-rigor, on-demand read-only codebase audit via specialized skills
• 🔬 External Skill Curation Pipeline — Opt-in discovery, quarantine, evaluation, and promotion of external skill candidates from configured sources (disabled by default; enable via external_skills.curation_enabled: true in config). Includes 7 tools: external_skill_discover, external_skill_list, external_skill_inspect, external_skill_promote, external_skill_reject, external_skill_delete, external_skill_revoke. Candidates pass through a 3-gate validation pipeline before evaluation: prompt injection scan (12 regex patterns), unsafe instruction scan (25 patterns), and provenance integrity check (SHA-256, timestamp, URL, publisher, and hash verification).
• 🎯 Governed Skill Optimizer — Manually-activated, single-skill optimizer (/swarm skill-opt plan|run|status|diff|approve|reject|rollback|history) that drives one allowlisted SKILL.md candidate at a time through deterministic draft → smoke → evaluation-substrate validation → manual approval → atomic activation/rollback. Bounded, restartable, reversible, and unable to mutate source/harness/security surfaces. Disabled by default (skill_opt.enabled: false); see docs/skill-optimizer.md.
• 🔄 Phase completion gates — completion-verify and drift verifier gates enforced before phase completion
• 🔁 Resumable sessions — all state saved to .swarm/; pick up any project any day
• 🖥️ PR Monitor — GitHub PR subscription and background polling via gh CLI; delivers real-time CI, review, and merge status updates via the AutomationEventBus (FR-001, opt-in via pr_monitor.enabled: true). Subscribe with /swarm pr subscribe ; unsubscribe with /swarm pr unsubscribe ; check status with /swarm pr status. With auto_pr_feedback: true, CI failures and merge conflicts mechanically activate PR_FEEDBACK only when no other workflow owns the session; otherwise they are durably queued for a later round.
• 🌐 13 full language profiles (TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP) with tree-sitter parse validation across 20 grammars (adds CSS, Bash, PowerShell, INI, Regex — and .tsx / .c aliases) — extending: see docs/adding-a-language.md
• 🛡️ Built-in security — SAST, secrets scanning, dependency audit per task
• 🔒 Scope enforcement — Validates write targets against declared scope with cross-process persistence, TTL expiry, and scope-aware destructive command blocking. Handles both single-string and array-based path arguments (files[], paths[], targetFiles[]) to prevent scope bypass via multi-file tool calls.
• 📝 Shell write detection — Static analysis of POSIX/PowerShell/cmd commands to detect file writes (redirects, builtins, in-place editors, network downloads, archive extraction, git destructive ops) before execution
• 🆓 Free tier — works with OpenCode Zen’s free model roster
• ⚙️ Fully configurable — override any agent’s model, disable agents, tune guardrails

The Swarm architect coordinates all internal agents automatically. You never manually switch between internal roles. If the active OpenCode agent is not a Swarm architect, the plugin workflow is bypassed.

---

Shell Write Detection

Swarm includes comprehensive static analysis for shell commands to detect and intercept file write operations before execution.

Shell Write Detection Features

• POSIX shell detection — Parses commands with bash-parser AST for accurate detection of:

  • Redirect operators (>, >>, >|, <<, <<-)
  • Here-documents and here-strings
  • Write-effect builtins (cp, mv, install, ln, truncate, dd)
  • In-place editors (sed -i, perl -i, awk -i)
  • Interpreter eval (python -c, node -e, bun -e, ruby -e, php -r)
  • Network downloaders (curl -o, wget -O, scp)
  • Archive extraction (tar -x, unzip, gunzip)
  • Git destructive operations (git clean -fd, git reset --hard)

• Windows shell detection — Uses regex heuristics for PowerShell and cmd.exe:

  • PowerShell cmdlets: Out-File, Set-Content, Add-Content, Copy-Item, Move-Item
  • cmd.exe builtins: copy, move, ren, del, rd, md
  • Redirect operators (>, >>)

• Interactive session denial — Blocks commands that create persistent or open-ended sessions:

  • POSIX: watch, screen, tmux new-session
  • PowerShell: Start-Process

• Cross-process scope enforcement — Declared scope is persisted to .swarm/scopes/scope-{taskId}.json with:

  • TTL expiry (default 24 hours)
  • Symlink guards (O_NOFOLLOW + realpath containment)
  • Schema versioning and fail-closed validation
  • Scope-aware destructive command blocking — Recursive delete patterns (rm -rf, rmdir /s, del /s, Remove-Item -Recurse, rsync --delete) are blocked unless ALL target paths are within the declared scope (coder agents only)

Security Patterns

The guardrails system blocks destructive shell commands targeting:

• System paths (/root, /etc, C:\Windows, etc.)
• Symlink/junction creation with external targets
• File operations under .swarm/ directory
• Fork bombs and infinite loops
• Disk wiping and ransomware-grade operations

---

What Actually Happens

You say:

Build me a JWT auth system.

Swarm then:

1. Clarifies only what it cannot infer.
2. Scans the codebase to understand what already exists.
3. Consults domain experts when needed and caches the guidance.
4. Writes a phased implementation plan.
5. Sends that plan through a critic gate before coding starts.
6. Executes tasks through the QA pipeline — one at a time, or concurrently in isolated worktrees for plans with provably file-disjoint task groups (v8 default for new plans, #1674; serial is the automatic fallback when scopes overlap or are unknown):

• coder writes code
• automated checks run
• reviewer checks correctness
• test engineer writes and runs tests
• architect runs regression sweep
• failures loop back with structured feedback

7. After each phase, docs and retrospectives are updated.

All project state lives in .swarm/ — plans, evidence, context, knowledge, and telemetry. Resumable by design. If .swarm/ already exists, the architect goes straight into RESUME → EXECUTE instead of repeating discovery.

---

Execution Modes

Swarm has two independent mode systems:

Session modes — toggle per session with a slash command:

Auto-proceed — a session toggle (/swarm auto-proceed [on|off]) that skips the “Ready for Phase N+1?” prompt at phase boundaries. Defaults to false; set as a plan default via execution_profile.auto_proceed during QA GATE SELECTION. Session override always wins. Independent of Full-Auto.

Full-Auto reduces approval friction by deterministically allowing safe operations (read-only tools, in-scope writes, safe shell) and routing every ambiguous or high-risk action (writes to plugin/build/guardrail paths, network, dependency changes, plan/phase mutations, subagent delegation) through the read-only critic_oversight agent before it executes. Denials are returned to the agent as structured signals so it can choose a safer path; repeated denials pause the run; phase completion requires an APPROVED oversight record. See docs/modes.md for mode, permission_policy, denials, and oversight config keys, fail-closed semantics, and recovery from a paused run.

Project mode — persistent via execution_mode config key:

Switch session modes with /swarm turbo [on|off] or /swarm full-auto [on|off]. Control phase-boundary auto-proceed with /swarm auto-proceed [on|off]. Set project mode in config. Lean Turbo is configured in turbo.lean.* in config and composes with all session modes. See docs/modes.md.

---

Quick Start

→ For a complete first-run walkthrough, see Getting Started.

The 15-minute guide covers:

• Installation (bunx opencode-swarm install)
• First-run auto-configuration (architect selected automatically)
• Running your first task
• Troubleshooting common issues

The installer automatically:

• Creates a project config at .opencode/opencode-swarm.json when missing so project-level overrides have a place to live
• Adds opencode-swarm to the OpenCode plugin list
• Disables the native explore and general agents to reduce routing conflicts

---

30-Second Demo

No animated GIF is shipped in the repo — instead, here is the exact terminal session you can record yourself with asciinema rec demo.cast (or any screen recorder). Every command below is real and runs against this repo as published.

Recording script (copy/paste-able, ~30 seconds):

# 1. Install the plugin (5s)
bunx opencode-swarm install

# 2. Open opencode and select a Swarm architect if it is not already active
opencode

# 3. Inside the OpenCode session, verify Swarm is live (5s)
/swarm help
/swarm agents

# 4. Kick off a task — the architect plans, then gates fire automatically (15s)
Build me a JWT auth helper with tests.

# 5. Watch the gates land in real time (5s)
/swarm status
/swarm evidence

ASCII storyboard of what a viewer should see:

┌──────────────────────────────────────────────────────────────┐
│ $ bunx opencode-swarm install                                │
│ ✓ installed opencode-swarm                                   │
│ ✓ created .opencode/opencode-swarm.json                     │
│                                                              │
│ $ opencode                                                   │
│ [Swarm] Welcome! Architect auto-selected. Type /swarm help  │
│                                                              │
│ > /swarm help                                                │
│ Available commands: status, plan, agents, help, diagnose... │
│                                                              │
│ > Build me a JWT auth helper with tests.                     │
│ [architect]  PLAN → critic gate → APPROVED                   │
│ [coder]      task 1.1 implementing…                          │
│ [reviewer]   correctness OK                                  │
│ [test_eng.]  3 tests written, 3 pass                         │
│ [architect]  regression sweep clean → phase_complete         │
│                                                              │
│ > /swarm evidence                                            │
│ task 1.1: review ✓  tests ✓  sast ✓  secrets ✓  drift ✓      │
└──────────────────────────────────────────────────────────────┘

Each row corresponds to a real gate documented further down this README — none are simulated.

---

Upgrading

OpenCode caches plugins indefinitely. A normal OpenCode restart does not pull newer versions from npm — once a plugin is cached, OpenCode keeps using that exact copy on every subsequent launch (issue #675). The cache lives in several places depending on your platform and OpenCode version:

• Current OpenCode cache layout: ~/.cache/opencode/node_modules/opencode-swarm/
• Legacy Linux / devcontainers / GitHub Codespaces: ~/.config/opencode/node_modules/opencode-swarm/
• Package cache layout: ~/.cache/opencode/packages/opencode-swarm@latest/
• Platform-specific macOS / Windows cache roots: ~/Library/Caches/opencode/..., %LOCALAPPDATA%\opencode\..., or %APPDATA%\opencode\...

The updater also clears known OpenCode lock files (bun.lock, bun.lockb, and package-lock.json) so the next start resolves the latest package.

To upgrade to the latest published version (clears both layouts automatically):

bunx opencode-swarm update     # cache-only refresh, then restart opencode
# or
bunx opencode-swarm install    # full reinstall (re-asserts config), then restart opencode

/swarm diagnose shows the running version and, when available, the latest version on npm so you can tell at a glance whether your cache is stale.

To disable the background staleness check entirely, set version_check: false in your opencode-swarm.json.

---

Commands

Common subcommands at a glance:

/swarm help [command]      # List all commands or get detailed help for a specific command
/swarm status              # Current phase and task
/swarm show-plan [N]       # Full plan or filtered by phase
/swarm agents              # Registered agents and models
/swarm diagnose            # Health check
/swarm evidence [task]     # Test and review results
/swarm reset --confirm     # Clear swarm state

Use /swarm help to see all available commands categorized by function. Use /swarm help for detailed usage information on a specific command.

Nine commands display a ⚠️ warning in help output because they share names with Claude Code built-in slash commands (e.g., /plan, /reset, /status). The warning reminds you to always use /swarm — the bare CC command does something different and sometimes destructive. See docs/commands.md#claude-code-command-conflicts for the full conflict registry.

See docs/commands.md for the full reference. The live source of truth is src/commands/registry.ts, which includes canonical commands, compound commands, and deprecated aliases.

Command Aliases

Some commands are available under deprecated names for backwards compatibility. Using the canonical name is recommended:

Aliases are hidden from help output but still function. The canonical command should be used in scripts and documentation.

---

The Agents

Swarm registers a roster of specialized core, optional, and conditional agents. The exact count shifts as agents are added or feature-flagged, so treat /swarm agents as the live source of truth — that command lists what is actually registered in your session. You don’t manually switch between them — the architect coordinates automatically.

Legend: Core = always available, Optional = available by default (can be disabled), Conditional = requires specific feature config (ui_review or council)

Run /swarm status and /swarm agents to see what’s active.

graph TB
    subgraph Orchestration
        A[Architect]
    end

    subgraph Discovery
        E[Explorer]
    end

    subgraph Execution
        C[Coder]
        T[Test Engineer]
        D[Designer]
    end

    subgraph Quality
        R[Reviewer]
        CR[Critic]
        CO[Critic Oversight]
        CSB[Critic Sounding Board]
        CDV[Critic Drift Verifier]
        CHV[Critic Hallucination Verifier]
    end

    subgraph Support
        S[SME]
        DOC[Docs]
        CI[Curator Init]
        CP[Curator Phase]
    end

    subgraph Council
        CM[Council Member]
        CMO[Council Moderator]
    end

    A -->|Discover| E
    E -->|Context| A
    A -->|Consult| S
    S -->|Guidance| A
    A -->|Design| D
    D -->|Scaffold| C
    A -->|Implement| C
    C -->|Review| R
    R -->|Verify| A
    C -->|Test| T
    T -->|Results| A
    A -->|Deliberate| CM
    CM -->|Verdict| A

---

How It Compares

---

LLM Provider Guide

Swarm works with any provider supported by OpenCode.

Free Tier (OpenCode Zen)

No API key required. Excellent starting point:

{
  "agents": {
    "coder": { "model": "opencode/minimax-m2.5-free" },
    "reviewer": { "model": "opencode/big-pickle" },
    "explorer": { "model": "opencode/big-pickle" }
  }
}

Paid Providers

For production, mix providers by role:

Provider Formats

Model Fallback

Automatic fallback to a secondary model on transient errors:

{
  "agents": {
    "coder": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "fallback_models": ["opencode/gpt-5-nano"]
    }
  }
}

See docs/configuration.md for full configuration reference.

---

---

Supported Languages

Full Tier-1 support: TypeScript, JavaScript, Python, Go, Rust Tier-2 support: Java, Kotlin, C#, C/C++, Swift Tier-3 support: Dart, Ruby, PHP/Laravel

All binaries optional. Missing tools produce soft warnings, never hard-fail.

---

Testing

6,000+ tests. Unit, integration, adversarial, and smoke. Run with:

bun test

---

Design Principles

1. Plan before code. Critic approves the plan before a single line is written.
2. One task at a time. Coder gets one task and full context. Nothing else.
3. Review everything immediately. Correctness, security, tests, adversarial tests. Every task.
4. Different models catch different bugs. Blind spots of the coder are the reviewer’s strength.
5. Save everything to disk. Resume any project any day from .swarm/ state.
6. Document failures. Rejections and retries recorded. After 5 failures, escalate to you.

---

Documentation

• Getting Started — 15-minute first-run guide
• Documentation Index — navigate all docs
• Installation Guide — comprehensive reference
• Architecture Deep Dive — control model, pipeline, tools
• Design Rationale — why every major decision
• Commands Reference — /swarm subcommands grouped by function
• Modes Guide — session modes (Turbo, Full-Auto) and project modes (strict/balanced/fast)
• Configuration — all config keys and examples
• Planning Guide — task format, phase structure, sizing

---

License

MIT

---

Stop hoping your agents figure it out. Start shipping code that actually works.