███████╗██╗ ██╗ █████╗ ██████╗ ███╗ ███╗
██╔════╝██║ ██║██╔══██╗██╔══██╗████╗ ████║
███████╗██║ █╗ ██║███████║██████╔╝██╔████╔██║
╚════██║██║███╗██║██╔══██║██╔══██╗██║╚██╔╝██║
███████║╚███╔███╔╝██║ ██║██║ ██║██║ ╚═╝ ██║
╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝
\ ` - ' /
- .(o o). -
( >.< ) Break big tasks into small ones.
/| |\ Spawn agents to work in parallel.
(_| |_) Learn from what works.
bzzzz...
AI agents that coordinate, learn, and survive context death.
# Install
npm install -g opencode-swarm-plugin@latest
# Set up (one-time)
swarm setup
# Use it
/swarm "Add OAuth authentication"That's it. The coordinator breaks the task into pieces, spawns parallel workers, tracks progress, and learns what works.
In any OpenCode session:
/swarm "Add user authentication with OAuth"
What happens:
- Coordinator analyzes - queries CASS (past agent sessions) for similar work
- Picks a strategy - file-based, feature-based, or risk-based decomposition
- Creates cells - git-backed work items in the hive:
Epic: Add OAuth ├─ Cell 1: OAuth provider integration (src/auth/oauth.ts) ├─ Cell 2: Session management (src/auth/session.ts) └─ Cell 3: Integration tests (tests/auth/) - Spawns workers - parallel agents with file reservations (no conflicts)
- Coordinates via Swarm Mail - agents message each other through actor-model primitives
- Checkpoints progress - survives context compaction at 25%, 50%, 75%
- Reviews work - coordinator validates each subtask before approval
- Records outcome - fast+success = good signal, slow+errors = bad signal
Next time you ask for something similar, it remembers what worked.
Workers don't wait for each other. File reservations prevent conflicts. Swarm Mail coordinates dependencies.
Every outcome feeds back into strategy selection. Patterns that fail >60% get auto-inverted to anti-patterns. Confidence decays over 90 days unless revalidated.
Checkpoints capture state in libSQL (embedded SQLite). When OpenCode compacts context, swarms resume from last checkpoint. No external servers.
Swarm Mail: DurableMailbox, DurableLock, DurableDeferred built on event sourcing. Full audit trail, exactly-once processing, type-safe with Effect-TS.
The "hive" is a .hive/ directory in your repo. Work items (cells) sync via git. Distributed coordination without a server.
Skills are packages of domain knowledge. Load testing-patterns for Feathers seams, swarm-coordination for multi-agent workflows, or create your own.
CASS indexes all your AI coding sessions (Claude, Cursor, Aider, etc). Query before solving - someone might've solved it already.
Coordinator reviews worker output before approval. 3-strike rule: after 3 rejections, task is blocked (signals architectural problem).
"Add OAuth"
│
▼
┌────────────────────────┐
│ COORDINATOR │
│ │
│ 1. Query CASS: │
│ "How did we solve │
│ this before?" │
│ │
│ 2. Pick strategy: │
│ file-based? │
│ feature-based? │
│ risk-based? │
│ │
│ 3. Break into pieces │
└────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Worker A │ │ Worker B │ │ Worker C │
│ │ │ │ │ │
│ auth/oauth │ │ auth/session│ │ auth/tests │
│ 🔒 files │ │ 🔒 files │ │ 🔒 files │
│ │ │ │ │ │
│ "I need │──────►│ "Got it, │ │ "Running │
│ session │ │ here's the │ │ tests..." │
│ types" │ │ interface" │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ │ │
└─────────────────────┼─────────────────────┘
│
▼
┌────────────────────────┐
│ LEARNING SYSTEM │
│ │
│ "File-based split │
│ worked well for │
│ auth - 3 workers, │
│ 15 min, 0 conflicts" │
│ │
│ Next time: use this │
│ pattern again │
└────────────────────────┘
swarm setup # Install and configure (one-time)
swarm doctor # Check dependencies (CASS, UBS, Ollama)
swarm init # Initialize hive in current project
swarm config # Show config file pathsWant to understand the internals? Here's the deep dive:
- 📚 Full Documentation - complete guides
- 🏗️ Architecture - event sourcing, durable primitives
- 🐝 Swarm Mail - actor-model coordination
- 🧠 Learning System - confidence decay, pattern maturity
- 🔧 Monorepo Guide - for contributors
Everything runs in-process. No external servers.
┌─────────────────────────────────────────────────────────────────┐
│ YOUR TASK │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ DECOMPOSITION strategy selection, subtask creation │
│ (queries CASS, semantic memory) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ HIVE git-backed work items for each subtask │
│ (atomic epic + cell creation) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ SWARM MAIL actor-model coordination (local-first) │
│ (DurableMailbox, DurableLock, libSQL) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ LIBSQL embedded SQLite, event-sourced state │
│ (append-only log, materialized views) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ LEARNING outcomes feed back into decomposition │
│ (confidence decay, pattern maturity) │
└─────────────────────────────────────────────────────────────────┘
All state is stored as an append-only event log:
Event Log (libSQL)
├─ agent_registered → Agent joins swarm
├─ message_sent → Agent-to-agent communication
├─ file_reserved → Exclusive file lock acquired
├─ file_released → Lock released
├─ swarm_checkpointed → Progress snapshot saved
├─ decomposition_generated → Task broken into subtasks
└─ subtask_outcome → Worker completion result
Materialized Views (derived from events)
├─ agents → Active agents per project
├─ messages → Agent inbox/outbox
├─ file_reservations → Current file locks
└─ eval_records → Outcome data for learning
Why event sourcing?
- Audit trail - full history of what happened
- Replay - reconstruct state from events
- Debugging - see exactly what went wrong
- Learning - analyze outcomes over time
Workers coordinate via Swarm Mail, an event-sourced actor model built on local-first primitives.
What makes it different:
- Actor model over durable streams - DurableMailbox, DurableLock, DurableDeferred
- Local-first with libSQL - embedded SQLite, no external servers, survives across sessions
- Event-sourced coordination - append-only log, materialized views, full audit trail
- Context-safe by design - hard caps on inbox (max 5 messages), thread summarization, body-on-demand
┌──────────────────────────────────────────────────────────────┐
│ SWARM MAIL │
│ │
│ Worker A: "I need the SessionUser type" │
│ ↓ │
│ Worker B: "Here's the interface:" │
│ interface SessionUser { │
│ id: string │
│ email: string │
│ roles: string[] │
│ } │
│ ↓ │
│ Worker A: "Got it, implementing OAuth flow now" │
│ │
└──────────────────────────────────────────────────────────────┘
File reservations prevent conflicts:
- Worker A reserves
src/auth/oauth.ts(exclusive via DurableLock) - Worker B tries to reserve it → blocked
- Worker B waits or works on something else
Inbox limits prevent context bloat:
- Max 5 messages per fetch (headers only)
- Read individual message bodies on demand
- Thread summarization for long conversations
All coordination state survives context compaction and session restarts.
Swarm Mail is built on Durable Streams primitives (inspired by Kyle Matthews' Electric SQL patterns):
┌─────────────────────────────────────────────────────────────┐
│ SWARM MAIL STACK │
├─────────────────────────────────────────────────────────────┤
│ │
│ TIER 3: COORDINATION │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ ask<Req, Res>() - Request/Response (RPC-style) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │ │
│ TIER 2: PATTERNS ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ DurableMailbox │ │ DurableLock │ │
│ │ Actor Inbox │ │ File Mutex │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │ │
│ TIER 1: PRIMITIVES ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ DurableCursor │ │ DurableDeferred │ │
│ │ Checkpointed │ │ Distributed │ │
│ │ Reader │ │ Promise │ │
│ └─────────────────┘ └─────────────────┘ │
│ │ │
│ STORAGE ▼ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ libSQL (Embedded SQLite) + Migrations │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Tier 1 - Primitives:
- DurableCursor - Positioned event stream consumption with checkpointing (exactly-once)
- DurableDeferred - URL-addressable distributed promises for async coordination
- DurableLock - CAS-based mutual exclusion for file reservations (TTL + retry/backoff)
Tier 2 - Patterns:
- DurableMailbox - Actor inbox with typed envelopes (sender, replyTo, payload)
- File reservation protocol built on DurableLock
Tier 3 - Coordination:
- ask() pattern - Synchronous-style RPC over async streams (creates DurableDeferred, appends to mailbox, returns promise)
Agent A Event Stream Agent B
│ │ │
│ ask("get SessionUser") │ │
├───────────────────────────>│ │
│ (creates deferred) │ │
│ │ consume event │
│ ├────────────────────────>│
│ │ │
│ │ reply to deferred │
│ │<────────────────────────┤
│ await deferred.value │ │
│<───────────────────────────┤ │
│ │ │
│ SessionUser interface │ │
│ │ │
Why this matters:
- No external servers (Redis, Kafka, NATS) - just libSQL
- Full audit trail - every message is an event
- Resumable - cursors checkpoint position, survive crashes
- Type-safe - Effect-TS with full inference
Architecture deep-dive: See Swarm Mail Architecture for complete implementation details, database schemas, and Effect-TS patterns.
OpenCode compacts context when it gets too long. Swarms survive this.
Session 1 Context Session 2
│ Compacts │
▼ 💥 ▼
┌─────────────────┐ ┌─────────────────┐
│ swarm running │ │ swarm_recover() │
│ ├─ 25% ✓ saved │ │ │ │
│ ├─ 50% ✓ saved │ ─────────────────────────────────►│ ▼ │
│ └─ 75% ✓ saved │ checkpoints survive │ resume at 75% │
└─────────────────┘ └─────────────────┘
Checkpoints capture:
- Which subtasks are done/in-progress/pending
- File reservations (who owns what)
- Shared context for workers
- Progress percentage
Recovery restores:
- Swarm state from last checkpoint
- File locks (prevents conflicts)
- Worker context (what they were doing)
All stored in libSQL (embedded SQLite) - no external servers, survives across sessions.
Every swarm completion records:
- Duration (how long did it take?)
- Errors (how many retries?)
- Files touched (did scope match prediction?)
- Success (did tests pass? were changes accepted?)
This feeds back into the decomposition strategy:
┌─────────────────────────────────┐
│ LEARNING LOOP │
└─────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ OUTCOMES │ │ PATTERNS │ │ ANTI-PATTERNS │
│ │ │ │ │ │
│ fast+success │ │ candidate │ │ >60% failure │
│ = good signal │──────────►│ ↓ │──────────►│ = auto-invert │
│ │ │ established │ │ │
│ slow+errors │ │ ↓ │ │ "split by X" │
│ = bad signal │ │ proven │ │ becomes │
│ │ │ │ │ "DON'T split │
└───────────────┘ └───────────────┘ │ by X" │
└───────────────┘
Confidence decays over 90 days
unless patterns are revalidated
Pattern maturity lifecycle:
candidate→ new pattern, low confidenceestablished→ validated 3+ timesproven→ 10+ successes (gets 1.5x weight in future decompositions)deprecated→ >60% failure rate (auto-inverted to anti-pattern)
Confidence decay: Patterns fade over 90 days unless revalidated. Prevents stale knowledge from dominating.
Skills are reusable knowledge packages. Load them on-demand for specialized tasks.
skills_use(name="testing-patterns") // Feathers seams + Beck's 4 rules
skills_use(name="swarm-coordination") // Multi-agent decompositionBundled skills:
testing-patterns- 25 dependency-breaking techniques, characterization testsswarm-coordination- Multi-agent decomposition, file reservationscli-builder- Argument parsing, help text, subcommandssystem-design- Architecture decisions, module boundarieslearning-systems- Confidence decay, pattern maturity
Create your own:
swarm init # Creates .opencode/skills/ in projectSkills can include:
- Step-by-step workflows
- Code examples
- Reference documentation
- Executable scripts
This is a Bun + Turborepo monorepo with two packages:
opencode-swarm-plugin/
├── packages/
│ ├── swarm-mail/ # Event sourcing primitives
│ │ └── src/streams/ # DurableMailbox, DurableLock, etc.
│ └── opencode-swarm-plugin/ # Main plugin
│ ├── src/ # Plugin tools
│ ├── global-skills/ # Bundled skills
│ └── docs/ # Architecture docs
├── package.json # Workspace root
└── turbo.json # Pipeline config
Standalone event sourcing package for multi-agent coordination:
EventStore- append-only event log with libSQLProjections- materialized views (agents, messages, reservations)- Effect-TS durable primitives (DurableMailbox, DurableCursor, DurableLock, DurableDeferred)
DatabaseAdapterinterface for dependency injection
OpenCode plugin providing:
- Hive integration (git-backed work item tracking)
- Swarm coordination (task decomposition, parallel agents)
- Agent Mail (inter-agent messaging)
- Learning system (pattern maturity, anti-pattern detection)
- Skills system (knowledge injection)
# Install all workspace dependencies
bun install
# Build all packages (respects dependency order)
bun turbo build
# Test all packages
bun turbo test
# Typecheck all packages
bun turbo typecheck
# Build/test specific package
bun turbo build --filter=swarm-mail
bun turbo test --filter=opencode-swarm-plugin
# Add dependency to specific package
cd packages/swarm-mail && bun add zodSee AGENTS.md for detailed monorepo guidance.
| Required | Optional |
|---|---|
| OpenCode | CASS - historical context |
| UBS - bug scanning | |
| Ollama - local embeddings for semantic memory |
Note: Semantic memory is embedded in the plugin. Install Ollama for vector search, or it falls back to full-text search.
Run swarm doctor to check status.
Inspiration & Core Ideas:
- MCP Agent Mail - THE INSPIRATION for multi-agent coordination. Swarm Mail is our implementation built on actor-model primitives (DurableMailbox, DurableLock) with local-first libSQL and event sourcing.
- Superpowers - verification patterns, Socratic planning, skill architecture
- Electric SQL - durable streams and event sourcing patterns that power Swarm Mail
- Evalite - outcome-based evaluation framework for learning systems
"With event sourcing, you can design an event such that it is a self-contained description of a user action." — Martin Kleppmann, Designing Data-Intensive Applications
MIT