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 >= 1.3.13 (bun --version to check), or Node.js >= 22.13 for npm installs (the Node-hosted sidecar uses the built-in node:sqlite). 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 unless their scopes are proven disjoint (v8 parallel lanes, Epic waves), and then each in its own isolated worktree.

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.
• 🌊 Epic Mode (opt-in preview) — one plan = one epic, run phase by phase as parallel waves of tasks whose declared scopes don’t conflict. The delegation gate enforces the active wave; in git projects each coder works in an isolated worktree on an epic branch that /swarm epic close squash-lands as staged changes. Per-task QA always runs, and a phase reviewer + critic gate (epic_phase_review) runs before phase_complete. Epic learns per-file write risk across epics, suggests plan restructurings with a predicted speedup, and reports a scorecard (/swarm epic report). Enable with epic.mode.enabled: true; see docs/modes.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
• 🔀 GitLab as a first-class forge (#2733) — MR and issue URLs (https:///owner/repo/-/merge_requests/N, /-/issues/N) are accepted by /swarm pr-review, pr-feedback, pr subscribe/unsubscribe, ci-monitor, publication recording, and issue ingestion, with self-hosted instance hosts derived from the remote or forge.base_url (config forge: { provider, base_url }, default auto; ambiguous remotes fail closed). Every URL-security control (HTTPS-only, private/localhost rejection, IDN protection, credential stripping) applies identically to GitLab. The glab binary resolves through the same hardened resolver contract as gh (OPENCODE_SWARM_GLAB_BINARY env override). Honest capability reporting: GitLab does not synthesize GitHub’s statusCheckRollup/reviewDecision/mergeStateStatus — those surface an explicit unavailable result instead of a fabricated value, and glab-backed live MR polling is tracked as follow-up issue #2882.
• 🖥️ 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

  With Epic Mode on, epic_next_wave issues each phase as waves of conflict-free tasks (the same per-task pipeline runs inside every wave), and epic_phase_review runs a reviewer + critic over the whole phase before phase_complete.

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.

Epic binds to the current plan and runs fully on OpenCode 1.x and OpenCode 2 (7.x plugin). On OpenCode 2 the v2 adapter ships a session-capable client, places coder worktree sessions with an eager parented create that is then moved into the worktree (#3169 Phase 3; #3558), and — since #3169 Phase 4 — dispatches human-typed /swarm commands natively, so the full flow (/swarm epic start → waves → phase review → close) is available there; the remaining live-host verification legs are tracked on #3169, and the dual-host CI lane has landed (merge-queue v2 smoke cell, weekly host-contract v2 digest, and a vendored-pin freshness notice). The epic itself is always opened by the user (human-only policy — the agent cannot start one on any host). /swarm epic start also refuses plans too small to benefit and suggests Balanced. The epic_next_wave tool then dispatches each phase as waves of tasks whose declared scopes don’t conflict; in a git project each coder works in an isolated worktree on an epic branch, and /swarm epic close squash-lands the work as staged changes for you to review. Every task in a wave still runs the full per-task QA pipeline (Stage A and Stage B). Epic learns which files tasks tend to write together and uses it to plan later waves and epics. See docs/modes.md; maintainers start with src/epic/README.md.

Project mode — persistent via execution_mode config key:

Switch session modes with /swarm turbo [on|off], /swarm full-auto [on|off], or /swarm epic start|close (Epic needs "epic": {"mode": {"enabled": true}} in config). 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:

• Adds opencode-swarm to the OpenCode plugin list
• Disables the native explore and general agents to reduce routing conflicts

It does not create a project config. .opencode/opencode-swarm.json is opt-in — create it yourself only if you want project-level overrides of the global config.

---

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                                   │
│                                                              │
│ $ 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/
• Older bare package cache layout: ~/.cache/opencode/packages/opencode-swarm/
• 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 all known 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 epic status         # Open epic, current wave, landing state (Epic Mode)
/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

Both projects compared here have since been renamed: oh-my-opencode is now OmO and get-shit-done is now GSD Core. The table reflects them as they were when it was written (April 2026, v6.81.0) and has not been re-checked against their current releases.

---

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/nemotron-3-ultra-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 (including provider quota exhaustion — e.g. GitHub Copilot’s 429 quota exceeded monthly limit):

{
  "agents": {
    "coder": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "fallback_models": ["opencode/mimo-v2.6-flash-free"]
    }
  }
}

Fallback applies to dispatched subagents and to primary (interactive) sessions alike. For a primary session, a fallback-eligible provider failure on one turn switches the session’s next message to the configured fallback (sticky for the session; announced by a MODEL FALLBACK: advisory and a model_fallback telemetry event). Recovery boundaries: session end (or a new session), 30 minutes without any message on the session, or a change to the configured model chain (the stale selection then reads as absent and the primary is retried). Switching the session’s agent away from the fallback-scoped role suppresses the override while the other agent is active, but the prior role’s selection persists until the idle window expires — switching back re-applies it. There is deliberately no in-session code escape (the host’s model-selection surface cannot distinguish a user re-pick from the session selection). A one-shot opencode run turn that already failed cannot be re-driven mid-turn — the OpenCode host owns the request loop — so interactive (TUI/GUI) sessions pick up the fallback on their next message, while a failed one-shot invocation simply ends; re-run it after resolving the quota.

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

Epic Mode’s planner regression harness: bun scripts/epic-bench.ts.

---

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. Tasks run in parallel (v8 lanes, Epic waves) only when their scopes are disjoint, each in an isolated worktree.
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, Epic) and project modes (strict/balanced/fast)
• Configuration — all config keys and examples
• Planning Guide — task format, phase structure, sizing
• Epic Mode maintainer guide — module map, invariants, shared-file seams

---

License

MIT

---

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