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
├── Security SME provides auth guidance
├── Architect creates phased plan with acceptance criteria
├── Phase 1: User model → QA → Tests → ✓
├── Phase 2: Auth logic → QA → Tests → ✓
├── Phase 3: Session management → QA → Tests → ✓
└── Result: Working code. Documented decisions. Resumable progress.
|
|
┌─────────────────────────────────────────────────────────────────────────┐
│ 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_security → auth best practices │
│ @sme_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 5: Execute (per task) │
│ │
│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │
│ │ @coder │ → │@security │ → │@auditor │ → │ @test │ │
│ │ 1 task │ │ review │ │ verify │ │ generate │ │
│ └─────────┘ └──────────┘ └─────────┘ └──────────┘ │
│ │ │ │
│ └──── If rejected: retry with feedback ────────┘ │
│ │
│ Update plan.md: [x] Task complete │
│ 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
├── context.md # Everything a new Architect needs
└── history/
├── phase-1.md # What was done, what was learned
└── phase-2.md
# 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
- 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# 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 Redis
## SME Guidance Cache
### Security (Phase 1)
- Never log tokens or passwords
- Use constant-time comparison for tokens
- Implement rate limiting on login
### API (Phase 1)
- Return 401 for invalid credentials (not 404)
- Include token expiry in response body
## Patterns 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.
Most frameworks use one model for everything. Same blindspots everywhere.
Swarm lets you mix models strategically:
{
"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" },
"security_reviewer": { "model": "openai/gpt-4o" },
"auditor": { "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 |
| SMEs | Domain knowledge | Fast recall, not deep reasoning |
| Security Reviewer | Finding flaws | Different vendor catches different bugs |
| Auditor | Verification | Independent perspective |
If Claude writes code and GPT reviews it, GPT catches Claude's blindspots. This is why real teams have code review.
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
{
"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" },
"_qa": { "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" },
"_qa": { "model": "ollama/qwen2.5:14b" }
}
}
}
}| Swarm | Agents |
|---|---|
cloud (default) |
architect, explorer, coder, sme_*, etc. |
local |
local_architect, local_explorer, local_coder, local_sme_*, etc. |
The first swarm (or one named "default") creates unprefixed agents. Additional swarms prefix all agent names.
In OpenCode, you'll see multiple architects to choose from:
architect- Cloud swarm (default)local_architect- Local swarm
Each architect automatically delegates to its own swarm's agents.
# Add to opencode.json
{
"plugin": ["opencode-swarm"]
}
# Or install via CLI
bunx opencode-swarm install| Agent | Role |
|---|---|
architect |
Central coordinator. Plans phases, delegates tasks, manages QA, maintains project memory. |
| Agent | Role |
|---|---|
explorer |
Fast codebase scanner. Identifies structure, languages, frameworks, key files. |
| Agent | Domain |
|---|---|
sme_web |
Flutter, React, Vue, Angular, JS/TS, HTML/CSS |
sme_api |
REST, GraphQL, OAuth, JWT, webhooks |
sme_database |
SQL Server, PostgreSQL, MySQL, MongoDB, Redis |
sme_devops |
Docker, Kubernetes, CI/CD, Terraform |
sme_security |
STIG, hardening, CVE, encryption, PKI |
sme_python |
Python ecosystem, libraries, patterns |
sme_powershell |
PowerShell scripting, modules, remoting |
sme_windows |
Windows internals, registry, services, WMI |
sme_linux |
Linux, systemd, package management |
sme_network |
TCP/IP, firewalls, DNS, TLS |
sme_azure |
Azure services, Entra ID, ARM/Bicep |
sme_vmware |
vSphere, ESXi, PowerCLI |
sme_oracle |
Oracle Database, SQL/PLSQL |
sme_active_directory |
AD, LDAP, Group Policy, Kerberos |
sme_ui_ux |
UI/UX design, accessibility |
| Agent | Role |
|---|---|
coder |
Implements ONE task at a time with full context |
test_engineer |
Generates tests for each completed task |
| Agent | Role |
|---|---|
security_reviewer |
Vulnerability assessment per task |
auditor |
Correctness verification per task |
Create ~/.config/opencode/opencode-swarm.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" },
"_qa": { "model": "google/gemini-2.0-flash" },
"test_engineer": { "model": "google/gemini-2.0-flash" }
}
}_sme→ All 15 SME agents_qa→ security_reviewer + auditor
Override specific agents:
{
"_sme": { "model": "google/gemini-2.0-flash" },
"sme_security": { "model": "anthropic/claude-sonnet-4-5" }
}{
"sme_vmware": { "disabled": true },
"sme_oracle": { "disabled": true }
}| 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 (security + audit) | Optional | Optional | Manual |
| Model mixing | Per-agent configuration | Limited | Limited | Manual |
| Resume projects | ✅ Native | ❌ | ❌ | Partial |
| SME domains | 15 specialized | Generic | Generic | Generic |
| Task granularity | One at a time | Batched | Batched | Varies |
- Plan before code - Documented phases with acceptance criteria
- One task at a time - Focused work, quality output
- QA everything immediately - Security + audit per task, not per project
- Cache SME knowledge - Don't re-ask answered questions
- Persistent memory -
.swarm/files survive sessions - Serial execution - Predictable, debuggable, no race conditions
- Heterogeneous models - Different perspectives catch different bugs
- User checkpoints - Confirm before proceeding to next phase
- Failure tracking - Document rejections, escalate after 3 attempts
- Resumable by design - Any Architect can pick up any project
MIT
Stop hoping your agents figure it out. Start shipping code that works.