Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review
npm install opencode-swarm
The only multi-agent framework that actually works.
Structured phases. Persistent memory. One task at a time. QA on everything.
Why Swarm? β’
How It Works β’
Installation β’
Agents β’
Configuration
---
``
You: "Build me an authentication system"
Other Frameworks:
βββ Agent 1 starts auth module...
βββ Agent 2 starts user model... (conflicts with Agent 1)
βββ Agent 3 starts database... (wrong schema)
βββ Agent 4 starts tests... (for code that doesn't exist yet)
βββ Result: Chaos. Conflicts. Context lost. Start over.
OpenCode Swarm:
βββ Architect analyzes request
βββ Explorer scans codebase (+ gap analysis)
βββ @sme consulted on security domain
βββ Architect creates phased plan with acceptance criteria
βββ @critic reviews plan β APPROVED
βββ Phase 1: User model β Review β Tests (run + PASS) β β
βββ Phase 2: Auth logic β Review β Tests (run + PASS) β β
βββ Phase 3: Session management β Review β Tests (run + PASS) β β
βββ Result: Working code. Documented decisions. Resumable progress.
`
---
$3- Parallel chaos, hope it converges | $3- Serial execution - predictable, traceable |
---
``
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β USER: "Add user authentication with JWT" β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 0: Check for .swarm/plan.md β
β Exists? Resume. New? Continue. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 1: Clarify (if needed) β
β "Do you need refresh tokens? What's the session duration?" β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 2: Discover β
β @explorer scans codebase β structure, languages, patterns β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 3: Consult SMEs (serial, cached) β
β @sme DOMAIN: security β auth best practices β
β @sme DOMAIN: api β JWT patterns, refresh flow β
β Guidance saved to .swarm/context.md β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 4: Plan β
β Creates .swarm/plan.md with phases, tasks, acceptance criteriaβ
β β
β Phase 1: Foundation [3 tasks] β
β Phase 2: Core Auth [4 tasks] β
β Phase 3: Session Management [3 tasks] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 4.5: Critic Gate β
β @critic reviews plan β APPROVED / NEEDS_REVISION / REJECTEDβ
β Max 2 revision cycles before escalating to user β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 5: Execute (per task) β
β β
β βββββββββββ ββββββββββββββ ββββββββββββββββ β
β β @coder β β β @reviewer β β β @test β β
β β 1 task β β check all β β write + run β β
β βββββββββββ ββββββββββββββ ββββββββββββββββ β
β β β β β
β β If REJECTED: retry If FAIL: fix + retest β
β βββββββββββββββββ β
β β
β Update plan.md: [x] Task complete (only if PASS) β
β Next task... β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β PHASE 6: Phase Complete β
β Re-scan with @explorer β
β Update context.md with learnings β
β Archive to .swarm/history/ β
β "Phase 1 complete. Ready for Phase 2?" β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
---
Other frameworks lose everything when the session ends. Swarm doesn't.
``
.swarm/
βββ plan.md # Your project roadmap (+ plan.json)
βββ context.md # Everything a new Architect needs
βββ evidence/ # Per-task execution evidence
β βββ 1.1/ # Evidence for task 1.1
β βββ 2.3/ # Evidence for task 2.3
βββ history/
βββ phase-1.md # What was done, what was learned
βββ phase-2.md
markdown
Project: Auth System
Current Phase: 2Phase 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
- Attempt 1: REJECTED - Missing expiration
- [ ] Task 2.3: Token validation middleware [MEDIUM]
- [BLOCKED] Task 2.4: Refresh tokens
- Reason: Waiting for decision on rotation strategy
`$3
`markdown
Project Context: Auth System
Technical Decisions
- Using bcrypt (cost 12) for password hashing
- JWT expires in 15 minutes, refresh in 7 days
- Storing refresh tokens in RedisSME Guidance Cache
$3
- Never log tokens or passwords
- Use constant-time comparison for tokens
- Implement rate limiting on login$3
- Return 401 for invalid credentials (not 404)
- Include token expiry in response bodyPatterns Established
- Error handling: Custom ApiError class with status codes
- Validation: Zod schemas in /validators/
`Start a new session tomorrow? The Architect reads these files and picks up exactly where you left off.
---
Heterogeneous Models = Better Code
Most frameworks use one model for everything. Same blindspots everywhere.
Swarm lets you mix models strategically:
`json
{
"agents": {
"architect": { "model": "anthropic/claude-sonnet-4-5" },
"explorer": { "model": "google/gemini-2.0-flash" },
"coder": { "model": "anthropic/claude-sonnet-4-5" },
"sme": { "model": "google/gemini-2.0-flash" },
"reviewer": { "model": "openai/gpt-4o" },
"critic": { "model": "google/gemini-2.0-flash" },
"test_engineer": { "model": "google/gemini-2.0-flash" }
}
}
`| Role | Optimized For | Why Different Models? |
|------|---------------|----------------------|
| Architect | Deep reasoning | Needs to plan complex work |
| Explorer | Fast scanning | Speed over depth |
| Coder | Implementation | Best coding model you have |
| SME | Domain knowledge | Fast recall, not deep reasoning |
| Reviewer | Finding flaws | Different vendor catches different bugs |
| Critic | Plan review | Catches scope issues before any code is written |
| Test Engineer | Test + run | Writes tests, runs them, reports PASS/FAIL |
If Claude writes code and GPT reviews it, GPT catches Claude's blindspots. This is why real teams have code review.
---
Multiple Swarms
Run different model configurations simultaneously. Perfect for:
- Cloud vs Local: Premium cloud models for critical work, local models for quick tasks
- Fast vs Quality: Quick iterations with fast models, careful work with expensive ones
- Cost Tiers: Cheap models for exploration, premium for implementation
$3
`json
{
"swarms": {
"cloud": {
"name": "Cloud",
"agents": {
"architect": { "model": "anthropic/claude-sonnet-4-5" },
"coder": { "model": "anthropic/claude-sonnet-4-5" },
"sme": { "model": "google/gemini-2.0-flash" },
"reviewer": { "model": "openai/gpt-4o" }
}
},
"local": {
"name": "Local",
"agents": {
"architect": { "model": "ollama/qwen2.5:32b" },
"coder": { "model": "ollama/qwen2.5:32b" },
"sme": { "model": "ollama/qwen2.5:14b" },
"reviewer": { "model": "ollama/qwen2.5:14b" }
}
}
}
}
`$3
| Swarm | Agents |
|-------|--------|
|
cloud (default) | architect, explorer, coder, sme, reviewer, critic, test_engineer |
| local | local_architect, local_explorer, local_coder, local_sme, local_reviewer, local_critic, local_test_engineer |The first swarm (or one named "default") creates unprefixed agents. Additional swarms prefix all agent names.
$3
In OpenCode, you'll see multiple architects to choose from:
-
architect - Cloud swarm (default)
- local_architect - Local swarmEach architect automatically delegates to its own swarm's agents.
---
Installation
`bash
Install via CLI (recommended)
bunx opencode-swarm install
`$3
`bash
Remove from opencode.json
bunx opencode-swarm uninstallRemove from opencode.json + clean up config files
bunx opencode-swarm uninstall --clean
`---
What's New
$3
- Canonical plan schema β Machine-readable plan.json with Zod-validated PlanSchema/TaskSchema/PhaseSchema. Automatic migration from legacy plan.md format. Structured status tracking (pending, in_progress, completed, blocked).
- Evidence bundles β Per-task execution evidence persisted to .swarm/evidence/. Five evidence types: review, test, diff, approval, note. Sanitized task IDs, atomic writes, configurable size limits. /swarm evidence to view, /swarm archive to manage retention.
- Per-agent guardrail profiles β Override guardrail limits for individual agents via guardrails.profiles. resolveGuardrailsConfig() merges base + profile with per-agent specificity.
- Context injection budget β max_injection_tokens config controls how much context is injected into system prompts. Priority-ordered: phase β task β decisions β agent context. Lower-priority items dropped when budget exhausted.
- Enhanced /swarm agents β Agent count summary, β‘ custom limits indicator for profiled agents, guardrail profiles section.
- Packaging smoke tests β CI-safe dist/ validation (8 tests).
- 208 new tests β 876 total tests across 39 files (up from 668 in v4.6.0).$3
- Circuit breaker β Two-layer protection against runaway agents. Soft warning at 50% of limits, hard block at 100%. Prevents infinite loops and runaway API costs.
- Detection signals β Tool call count, wall-clock time, consecutive repetition, and consecutive error tracking per agent session.
- Configurable limits β All thresholds tunable via guardrails config: max_tool_calls, max_duration_minutes, max_repetitions, max_consecutive_errors, warning_threshold.
- 46 new tests β 668 total tests across 30 files.$3
- Lint cleanup β Replaced string concatenation with template literals, documented as any casts with biome-ignore comments.
- Code deduplication β Extracted stripSwarmPrefix() utility to eliminate 3 duplicate prefix-stripping blocks.
- /swarm diagnose β Health check for .swarm/ files, plan structure, and plugin configuration.
- /swarm export β Export plan.md and context.md as portable JSON.
- /swarm reset --confirm β Clear swarm state files with safety confirmation.$3
- CLI uninstall command β Remove plugin with optional --clean flag.
- Custom error classes β SwarmError hierarchy with actionable guidance messages.
- /swarm history β View completed phases from plan.md.
- /swarm config β View current resolved plugin configuration.$3
- Path validation β validateSwarmPath() prevents directory traversal in .swarm/ file operations.
- Fetch hardening β 10s timeout, 5MB limit, retry logic for gitingest tool.
- Config limits β Deep merge depth limit (10), config file size limit (100KB).$3
- Hooks pipeline β safeHook() crash-safe wrapper, composeHandlers() for multi-handler composition.
- Context pruning β Token budget tracking with 70%/90% threshold warnings.
- Slash commands β /swarm status, /swarm plan, /swarm agents.
- Agent awareness β Activity tracking, delegation tracking, cross-agent context injection.All features are opt-in via configuration. See Installation Guide for config options.
---
Agents
$3
| Agent | Role |
|-------|------|
| architect | Central coordinator. Plans phases, delegates tasks, manages QA, maintains project memory. |$3
| Agent | Role |
|-------|------|
| explorer | Fast codebase scanner. Identifies structure, languages, frameworks, key files. |$3
| Agent | Role |
|-------|------|
| sme | Open-domain expert. The architect specifies any domain (security, python, ios, rust, kubernetes, etc.) per call. No hardcoded list β works with any domain the LLM has knowledge of. |$3
| Agent | Role |
|-------|------|
| coder | Implements ONE task at a time with full context |
| test_engineer | Generates tests, runs them, and reports structured PASS/FAIL verdicts |$3
| Agent | Role |
|-------|------|
| reviewer | Combined correctness + security review. The architect specifies CHECK dimensions (security, correctness, edge-cases, performance, etc.) per call. |
| critic | Plan review gate. Reviews the architect's plan BEFORE implementation β checks completeness, feasibility, scope, dependencies, and flags AI-slop. |---
Slash Commands
| Command | Description |
|---------|-------------|
|
/swarm status | Current phase, task progress, and agent count |
| /swarm plan [N] | View full plan or filter by phase number |
| /swarm agents | List all registered agents with models and permissions |
| /swarm history | View completed phases with status icons |
| /swarm config | View current resolved plugin configuration |
| /swarm diagnose | Health check for .swarm/ files and config |
| /swarm export | Export plan and context as portable JSON |
| /swarm reset --confirm | Clear swarm state files (with safety gate) |
| /swarm evidence [task] | View evidence bundles for a task or all tasks |
| /swarm archive [--dry-run] | Archive old evidence bundles with retention policy |---
Configuration
Create
~/.config/opencode/opencode-swarm.json:`json
{
"agents": {
"architect": { "model": "anthropic/claude-sonnet-4-5" },
"explorer": { "model": "google/gemini-2.0-flash" },
"coder": { "model": "anthropic/claude-sonnet-4-5" },
"sme": { "model": "google/gemini-2.0-flash" },
"reviewer": { "model": "openai/gpt-4o" },
"critic": { "model": "google/gemini-2.0-flash" },
"test_engineer": { "model": "google/gemini-2.0-flash" }
}
}
`$3
`json
{
"sme": { "disabled": true },
"test_engineer": { "disabled": true }
}
`---
Guardrails
OpenCode Swarm includes a built-in circuit breaker that prevents subagents from running away β burning API credits in infinite loops, repeating the same tool call, or spinning for hours.
$3
| Layer | Trigger | Action |
|-------|---------|--------|
| β οΈ Soft Warning | 50% of any limit reached | Injects warning message into agent's chat stream |
| π Hard Block | 100% of any limit reached | Blocks ALL further tool calls + injects stop message |
$3
| Signal | Default Limit | Description |
|--------|---------------|-------------|
| Tool calls | 200 | Total tool invocations per agent session |
| Duration | 30 min | Wall-clock time since delegation started |
| Repetition | 10 | Same tool + args called consecutively |
| Consecutive errors | 5 | Sequential null/undefined tool outputs |
$3
Guardrails are enabled by default. Customize in your swarm config:
`jsonc
{
"guardrails": {
"enabled": true, // default: true
"max_tool_calls": 200, // range: 10β1000
"max_duration_minutes": 30, // range: 1β120
"max_repetitions": 10, // range: 3β50
"max_consecutive_errors": 5, // range: 2β20
"warning_threshold": 0.5 // range: 0.1β0.9 (fraction of limit for soft warning)
}
}
`$3
Override limits for specific agents that need more (or less) room:
`jsonc
{
"guardrails": {
"max_tool_calls": 200,
"profiles": {
"coder": { "max_tool_calls": 500, "max_duration_minutes": 60 },
"explorer": { "max_tool_calls": 50 }
}
}
}
`Profiles merge with base config β only specified fields are overridden.
$3
`json
{
"guardrails": {
"enabled": false
}
}
`---
Comparison
| Feature | OpenCode Swarm | AutoGen | CrewAI | LangGraph |
|---------|---------------|---------|--------|-----------|
| Execution | Serial (predictable) | Parallel (chaotic) | Parallel | Configurable |
| Planning | Phased with acceptance criteria | Ad-hoc | Role-based | Graph-based |
| Memory | Persistent
.swarm/ files | Session only | Session only | Checkpoints |
| QA | Per-task (unified review) | Optional | Optional | Manual |
| Model mixing | Per-agent configuration | Limited | Limited | Manual |
| Resume projects | β
Native | β | β | Partial |
| SME domains | Open-domain (any) | Generic | Generic | Generic |
| Task granularity | One at a time | Batched | Batched | Varies |---
Design Principles
1. Plan before code - Documented phases with acceptance criteria
2. One task at a time - Focused work, quality output
3. Review everything immediately - Correctness + security review per task, not per project
4. Cache SME knowledge - Don't re-ask answered questions
5. Persistent memory -
.swarm/ files survive sessions
6. Serial execution - Predictable, debuggable, no race conditions
7. Heterogeneous models - Different perspectives catch different bugs
8. User checkpoints - Confirm before proceeding to next phase
9. Failure tracking - Document rejections, escalate after 5 attempts
10. Resumable by design - Any Architect can pick up any project---
Testing
`bash
Run all tests
bun testRun specific test file
bun test tests/unit/config/schema.test.ts
`876 unit tests across 39 files covering config, tools, agents, hooks, commands, state, guardrails, evidence, and plan schemas. Uses Bun's built-in test runner β zero additional test dependencies.
Troubleshooting
$3
1. Verify opencode-swarm is listed in your opencode.json plugins array
2. Run bunx opencode-swarm install to auto-configure
3. Run /swarm diagnose to check health status$3
- Ensure you're using /swarm , not /swarm/
- Run /swarm with no arguments to see available commands$3
- Swarm automatically detects .swarm/plan.md and resumes where you left off
- If you get unexpected behavior, run /swarm export to backup, then /swarm reset --confirm` to start fresh---
- Architecture Deep Dive
- Design Rationale
- Installation Guide
---
MIT
---
Stop hoping your agents figure it out. Start shipping code that works.