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

https://swarmai.site/

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)

save_plan({
  title: "My Project",
  swarm_id: "mega",
  phases: [{ id: 1, name: "Setup", tasks: [{ id: "1.1", description: "Initialize project" }] }],
  working_directory: "/path/to/project"  // Required - no fallback
})

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

{
  "context_budget": {
    "enabled": false
  }
}

{
  "context_budget": {
    "enabled": true,
    "max_injection_tokens": 4000,
    "warn_threshold": 0.7,
    "critical_threshold": 0.9,
    "enforce": true,
    "prune_target": 0.7,
    "preserve_last_n_turns": 4,
    "recent_window": 10,
    "tracked_agents": ["architect"],
    "enforce_on_agent_switch": true,
    "model_limits": { "default": 128000 },
    "tool_output_mask_threshold": 2000,
    "scoring": {
      "enabled": false,
      "max_candidates": 100,
      "weights": { "recency": 0.3, "relevance": 0.4, "importance": 0.3 },
      "decision_decay": { "mode": "exponential", "half_life_hours": 24 },
      "token_ratios": { "prose": 0.25, "code": 0.4, "json": 0.6, "logs": 0.1 }
    }
  }
}

{
  "context_budget": {
    "enabled": true,
    "max_injection_tokens": 2000,
    "warn_threshold": 0.5,
    "critical_threshold": 0.75,
    "enforce": true,
    "prune_target": 0.6,
    "preserve_last_n_turns": 2,
    "recent_window": 5,
    "tracked_agents": ["architect"],
    "enforce_on_agent_switch": true,
    "model_limits": { "default": 128000 },
    "tool_output_mask_threshold": 1500,
    "scoring": {
      "enabled": true,
      "max_candidates": 50,
      "weights": { "recency": 0.5, "relevance": 0.3, "importance": 0.2 },
      "decision_decay": { "mode": "linear", "half_life_hours": 12 },
      "token_ratios": { "prose": 0.2, "code": 0.35, "json": 0.5, "logs": 0.05 }
    }
  }
}

{
  "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 replaces soft advisory warnings with hard runtime blocks and adds structural compliance tooling for all model tiers.

• qaSkipCount reset fixed: The skip-detection counter in delegation-gate.ts now resets only when both reviewer and test_engineer have been seen since the last coder entry — not when either one runs alone.
• update_task_status reviewer gate check: Accepting status='completed' now validates that the reviewer gate is present in the session's gateLog for the given task. Missing reviewer returns a structured error naming the absent gate.
• Architect self-coding hard block: architectWriteCount ≥ 3 now throws an Error with message SELF_CODING_BLOCK (previously a warning only). Counts 1–2 remain advisory warnings. Counter resets on coder delegation.

Every task now has a tracked workflow state in the session:

Transitions are forward-only. advanceTaskState() throws INVALID_TASK_STATE_TRANSITION if an illegal jump is attempted. getTaskState() returns 'idle' for unknown tasks.

session.lastGateOutcome records the most recent gate result: { gate, taskId, passed, timestamp }.

• update_task_status now uses the state machine (not a raw gateLog.has() check): status='completed' is rejected unless the task is in 'tests_run' or 'complete' state.
• delegation-gate.ts protocol-violation check additionally verifies that the prior task's state has advanced past 'coder_delegated' before allowing a new coder delegation.

• Progressive task disclosure: When >5 tasks are visible in the last user message, delegation-gate.ts trims to the current task ± a context window. A [Task window: showing N of M tasks] comment marks the trim point.
• Deliberation preamble: Each architect turn is prefixed with [Last gate: {tool} {result} for task {taskId}] sourced from session.lastGateOutcome, prompting the architect to identify the single next step.
• Low-capability model detection: LOW_CAPABILITY_MODELS constant (matches substrings mini, nano, small, free) and isLowCapabilityModel(modelId) helper added to constants.ts.
• Behavioral guidance markers: Three <!-- BEHAVIORAL_GUIDANCE_START --> … <!-- BEHAVIORAL_GUIDANCE_END --> pairs wrap the BATCHING DETECTION, ARCHITECT CODING BOUNDARIES, and QA gate behavioral sections in the architect prompt.
• Tier-based prompt trimming: When session.activeModel matches isLowCapabilityModel(), the behavioral guidance blocks are stripped from the architect prompt and replaced with [Enforcement: programmatic gates active]. Programmatic enforcement substitutes for verbose prompt instructions on smaller models.

New architect-only tool and supporting runtime enforcement:

• declare_scope tool: Pre-declares which files the coder is allowed to modify for a given task. Input: { taskId, files, whitelist?, working_directory? }. Validates task ID format, plan membership, and non-complete state. On success, sets session.declaredCoderScope. Architect-only.
• Automatic scope from FILE: directives: When a coder delegation is detected, delegation-gate.ts extracts FILE: directive values and stores them as session.declaredCoderScope automatically — no explicit declare_scope call required.
• Scope containment tracking: guardrails.ts appends every file the architect writes to session.modifiedFilesThisCoderTask. On coder delegation start, the list resets to [].
• Violation detection: After a coder task completes, toolAfter compares modifiedFilesThisCoderTask against declaredCoderScope. If >2 files are outside the declared scope, session.lastScopeViolation is set. The next architect message receives a scope violation warning.
• isInDeclaredScope(filePath, scopeEntries): Module-level helper using path.resolve() + path.relative() for proper directory containment (not string matching).

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; supports parsing delegation envelopes from JSON or KEY: VALUE text format for validation.

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

Before escalating to the user, the Architect consults the critic in SOUNDING_BOARD mode. The critic returns one of four verdicts: UNNECESSARY, REPHRASE, APPROVED, or RESOLVE.

Three-tier escalation hierarchy ensures systematic problem resolution:

1. Tier 1: Self-resolve using existing context
2. Tier 2: Critic consultation via sounding board
3. Tier 3: User escalation (requires critic APPROVED)

After 3 coder rejections, the Architect intervenes to simplify the approach rather than adding more logic.

The mega-reviewer reconstructs developer intent from task specs and diffs before evaluating changes.

Changes classified as TRIVIAL, MODERATE, or COMPLEX receive appropriate review depth:

• TRIVIAL → Tier 1 only
• MODERATE → Tiers 1-2
• COMPLEX → All three tiers

Agents include one-line summaries in state events for downstream consumption by other agents.

Agents prefix outputs with [FOR: agent1, agent2] tags to prepare for v6.20's automatic context filtering.

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.