Your AI writes the code. Swarm makes sure it actually works.

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. Your project state is saved to disk, so you can close your laptop, come back tomorrow, and pick up exactly where you left off.

npm install -g opencode-swarm

That's it. Open your project with opencode and start building. Swarm activates automatically.

You say: "Build me a JWT auth system."

Here's what Swarm does behind the scenes:

1. Asks you clarifying questions (only the ones it can't figure out itself)
2. Scans your codebase to understand what already exists
3. Consults domain experts (security, API design, whatever your project needs) and caches the guidance so it never re-asks
4. Writes a phased plan with concrete tasks, acceptance criteria, and dependencies
5. A separate critic agent reviews the plan before any code is written
6. Implements one task at a time. For each task:
   • A coder agent writes the code
   • 7 automated checks run (syntax, imports, linting, secrets, security, build, quality)
   • A reviewer agent (running on a different AI model) checks for correctness
   • A test engineer agent writes tests, runs them, and checks coverage
   • If anything fails, it goes back to the coder with specific feedback
   • If it passes everything, the task is marked done and the next one starts
7. After each phase completes, documentation updates automatically, and a retrospective captures what worked and what didn't. Those learnings carry into the next phase.

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

.swarm/
├── plan.md       # Your project roadmap (tasks, status, what's done, what's next)
├── context.md    # Decisions made, expert guidance, established patterns
├── evidence/     # Review verdicts, test results, diffs for every completed task
└── history/      # Phase retrospectives and metrics

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

Most AI coding tools let one model write code and then ask that same model if the code is good. That's like asking someone to proofread their own essay. They'll miss the same things they missed while writing it.

Swarm fixes this by splitting the work across specialized agents and requiring that different models handle writing vs. reviewing. The coder writes. A different model reviews. Another model tests. Different training data, different blind spots, different failure modes.

The other thing most tools get wrong: they try to do everything in parallel. That sounds fast, but in practice you get three agents writing conflicting code at the same time with no coordination. Swarm runs one task at a time through a fixed pipeline. Slower per-task, but you don't redo work.

npm install -g opencode-swarm

Open a project with opencode and run:

/swarm diagnose

This checks that everything is wired up correctly.

By default, Swarm v6.14+ uses free OpenCode Zen models (no API key required). You can override any agent's model by creating .opencode/swarm.json in your project. See the LLM Provider Guide for all options.

{
  "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,
    "profiles": {
      "coder": { "max_tool_calls": 500 }
    }
  },
  "tool_filter": {
    "enabled": true,
    "overrides": {}
  },
  "review_passes": {
    "always_security_review": false,
    "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*"]
  },
  "automation": {
    "mode": "manual",
    "capabilities": {
      "plan_sync": false,
      "phase_preflight": false,
      "config_doctor_on_startup": false,
      "evidence_auto_summaries": false,
      "decision_drift_detection": false
    }
  }
}

You only need to specify the agents you want to override. The rest use the default.

Just tell OpenCode what you want to build. Swarm handles the rest.

> Build a REST API with user registration, login, and JWT auth

Use /swarm status at any time to see where things stand.

Swarm works with any LLM provider supported by OpenCode. Different agents benefit from different models — the architect needs strong reasoning, the coder needs strong code generation, and the reviewer benefits from a model different from the coder (to catch blind spots).

OpenCode Zen provides free models via the opencode/ provider prefix. These are excellent starting points and require no API key:

{
  "agents": {
    "coder":        { "model": "opencode/minimax-m2.5-free" },
    "reviewer":     { "model": "opencode/big-pickle" },
    "test_engineer":{ "model": "opencode/gpt-5-nano" },
    "explorer":     { "model": "opencode/trinity-large-preview-free" },
    "sme":          { "model": "opencode/trinity-large-preview-free" },
    "critic":       { "model": "opencode/trinity-large-preview-free" },
    "docs":         { "model": "opencode/trinity-large-preview-free" },
    "designer":     { "model": "opencode/trinity-large-preview-free" }
  }
}

Save this configuration to .opencode/swarm.json in your project root (or ~/.config/opencode/opencode-swarm.json for global config).

Note: The architect key is intentionally omitted — it inherits whatever model you have selected in the OpenCode UI for maximum reasoning quality.

For production use, mix providers to maximize quality across writing vs. reviewing:

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

MODE: EXECUTE (per task)
│
├── 5a. @coder implements (ONE task only)
├── 5b. diff + imports (contract + dependency analysis)
├── 5c. syntax_check (parse validation)
├── 5d. placeholder_scan (catches TODOs, stubs, incomplete code)
├── 5e. lint fix → lint check
├── 5f. build_check (does it compile?)
├── 5g. pre_check_batch (4 parallel: lint, secretscan, SAST, quality budget)
├── 5h. @reviewer (correctness pass)
├── 5i. @reviewer (security pass, if security-sensitive files changed)
├── 5j. @test_engineer (verification tests + coverage ≥70%)
├── 5k. @test_engineer (adversarial tests)
├── 5l. ⛔ Pre-commit checklist (all 4 items required, no override)
└── 5m. Task marked complete, evidence written

# Project: Auth System
Current Phase: 2

## Phase 1: Foundation [COMPLETE]
- [x] Task 1.1: Create user model [SMALL]
- [x] Task 1.2: Add password hashing [SMALL]
- [x] Task 1.3: Database migrations [MEDIUM]

## Phase 2: Core Auth [IN PROGRESS]
- [x] Task 2.1: Login endpoint [MEDIUM]
- [ ] Task 2.2: JWT generation [MEDIUM] (depends: 2.1) ← CURRENT
  - Acceptance: Returns valid JWT with user claims, 15-minute expiry
  - Attempt 1: REJECTED — missing expiration claim
- [ ] Task 2.3: Token validation middleware [MEDIUM]

## Technical Decisions
- bcrypt cost factor: 12
- JWT TTL: 15 minutes; refresh TTL: 7 days

## SME Guidance (cached, never re-asked)
### security (Phase 1)
- Never log tokens or passwords
- Rate-limit login: 5 attempts / 15 min per IP

### api (Phase 1)
- Return 401 for invalid credentials (not 404)

{
  "guardrails": {
    "profiles": {
      "coder": { "max_tool_calls": 500, "max_duration_minutes": 60 },
      "explorer": { "max_tool_calls": 50 }
    }
  }
}

{
  "gates": {
    "syntax_check": { "enabled": true },
    "placeholder_scan": { "enabled": true },
    "sast_scan": { "enabled": true },
    "quality_budget": {
      "enabled": true,
      "max_complexity_delta": 5,
      "min_test_to_code_ratio": 0.3
    }
  }
}

{
  "agents": {
    "architect": { "model": "anthropic/claude-opus-4-6" },
    "coder": { "model": "minimax-coding-plan/MiniMax-M2.5" },
    "explorer": { "model": "minimax-coding-plan/MiniMax-M2.1" },
    "sme": { "model": "kimi-for-coding/k2p5" },
    "critic": { "model": "zai-coding-plan/glm-5" },
    "reviewer": { "model": "zai-coding-plan/glm-5" },
    "test_engineer": { "model": "minimax-coding-plan/MiniMax-M2.5" },
    "docs": { "model": "zai-coding-plan/glm-4.7-flash" },
    "designer": { "model": "kimi-for-coding/k2p5" }
  },
  "guardrails": {
    "max_tool_calls": 200,
    "max_duration_minutes": 30,
    "profiles": {
      "coder": { "max_tool_calls": 500 }
    }
  },
  "review_passes": {
    "always_security_review": false,
    "security_globs": ["**/*auth*", "**/*crypto*", "**/*session*"]
  },
  "automation": {
    "mode": "manual",
    "capabilities": {
      "plan_sync": true,
      "phase_preflight": false,
      "config_doctor_on_startup": false,
      "config_doctor_autofix": false,
      "evidence_auto_summaries": true,
      "decision_drift_detection": true
    }
  },
  "knowledge": {
    "enabled": true,
    "swarm_max_entries": 100,
    "hive_max_entries": 1000,
    "auto_promote_days": 30,
    "max_inject_count": 5,
    "dedup_threshold": 0.6,
    "scope_filter": ["global"],
    "hive_enabled": true,
    "rejected_max_entries": 200,
    "validation_enabled": true,
    "evergreen_confidence": 0.8,
    "evergreen_utility": 0.5,
    "low_utility_threshold": 0.2,
    "min_retrievals_for_utility": 3,
    "schema_version": "v6.17"
  }
}

{
  "plan_cursor": {
    "enabled": true,
    "max_tokens": 1500,
    "lookahead_tasks": 2
  }
}

{
  "tool_output": {
    "truncation_enabled": true,
    "max_lines": 150,
    "per_tool": {
      "diff": 200,
      "symbols": 100
    }
  }
}

---
[output truncated to {maxLines} lines – use `tool_output.per_tool.<tool>` to adjust]

{
  "sme": { "disabled": true },
  "designer": { "disabled": true },
  "test_engineer": { "disabled": true }
}

Swarm limits which tools each agent can access based on their role. This prevents agents from using tools that aren't appropriate for their responsibilities, reducing errors and keeping agents focused.

Tool filtering is enabled by default. Customize it in your config:

{
  "tool_filter": {
    "enabled": true,
    "overrides": {
      "coder": ["diff", "imports", "lint", "symbols", "test_runner"],
      "reviewer": ["diff", "secretscan", "sast_scan", "symbols"]
    }
  }
}

If an agent reports it doesn't have access to a tool it needs:

1. Check if the tool is in the agent's default allocation (see table above)
2. Add a custom override in your config:

{
  "tool_filter": {
    "overrides": {
      "coder": ["diff", "imports", "lint", "symbols", "extract_code_blocks", "retrieve_summary", "test_runner"]
    }
  }
}

3. To completely disable filtering for all agents:

{
  "tool_filter": {
    "enabled": false
  }
}

The following tools can be assigned to agents via overrides:

This release adds enforcement-layer tooling and self-healing guardrails:

• phase_complete tool: Verifies all required agents were dispatched before a phase closes; emits events to .swarm/events.jsonl; configurable enforce/warn policy
• Summarization loop fix: exempt_tools config prevents retrieve_summary and task outputs from being re-summarized (fixes Issue #8)
• Same-model adversarial detection: Warns when coder and reviewer share the same model; warn/gate/ignore policy
• Architect test guardrail (HF-1b): Prevents architect from running full bun test suite — must target specific files one at a time
• Docs: docs/swarm-briefing.md (LLM pipeline briefing), Task Field Reference in docs/planning.md

• consolidateSystemMessages: Merges multiple system messages into one at index 0
• Test isolation helpers: createIsolatedTestEnv and assertSafeForWrite
• Coder self-verify guardrail (HF-1): Coder and test_engineer agents blocked from running build/test/lint
• /swarm template fix: {{arguments}} → $ARGUMENTS
• DEFAULT_MODELS update: claude-sonnet-4-5 → claude-sonnet-4-20250514, gemini-2.0-flash → gemini-2.5-flash

This release focuses on reducing context usage and improving mode-conditional behavior:

• Role-Scoped Tool Filtering: Agent tools filtered via AGENT_TOOL_MAP
• Plan Cursor: Compressed plan summary under 1,500 tokens
• Mode Detection: DISCOVER/PLAN/EXECUTE/PHASE-WRAP/UNKNOWN modes
• Tool Output Truncation: diff/symbols outputs truncated with footer
• ZodError Fixes: Optional current_phase, 'completed' status support

This release adds runtime detection hooks to catch and warn about architect workflow violations:

• Self-coding detection: Warns when the architect writes code directly instead of delegating
• Partial gate tracking: Detects when QA gates are skipped
• Self-fix detection: Warns when an agent fixes its own gate failure (should delegate to fresh agent)
• Batch detection: Catches "implement X and add Y" batching in task requests
• Zero-delegation detection: Warns when tasks complete without any coder delegation

These hooks are advisory (warnings only) and help maintain workflow discipline during long sessions.

6,000+ tests. Unit, integration, adversarial, and smoke. Zero additional test dependencies.

bun test

1. Plan before code. The critic approves the plan before a single line is written.
2. One task at a time. The 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. The coder's blind spot is the reviewer's strength.
5. Save everything to disk. Any session, any model, any day, pick up where you left off.
6. Document failures. Rejections and retries are recorded. After 5 failures, it escalates to you.

OpenCode Swarm v6.16+ ships with language profiles for 11 languages across three quality tiers. All tools use graceful degradation — if a binary is not on PATH, the tool skips with a soft warning rather than a hard failure.

Tier definitions:

• Tier 1 — Full pipeline: all tools integrated and tested end-to-end.
• Tier 2 — Strong coverage: most tools integrated; some optional (audit, SAST).
• Tier 3 — Basic coverage: core tools integrated; advanced tooling limited.

All binaries are optional. Missing tools produce a soft warning and skip — the pipeline never hard-fails on a missing linter or auditor.

See CHANGELOG.md for shipped features.

Upcoming: v6.14 focuses on further context optimization and agent coordination improvements.

• Architecture Deep Dive
• Design Rationale
• Installation Guide
• Linux + Docker Desktop Install Guide
• LLM Operator Installation Guide
• Pre-Swarm Planning Guide
• Swarm Briefing for LLMs

MIT

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