Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail
npm install opencode-swarm-pluginMulti-agent swarm coordination for OpenCode - break tasks into parallel subtasks, spawn worker agents, learn from outcomes.
π Website: swarmtools.ai
π Full Documentation: swarmtools.ai/docs

```
βββββββββββ βββ ββββββ βββββββ ββββ ββββ
βββββββββββ ββββββββββββββββββββββββ βββββ
βββββββββββ ββ ββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββ ββββββ ββββββ βββ βββ
ββββββββ ββββββββ βββ ββββββ ββββββ βββ
Bun is required. The CLI uses Bun-specific APIs and won't run with Node.js alone.
`bash`Install Bun (if you don't have it)
curl -fsSL https://bun.sh/install | bash
See bun.sh for other installation methods (Homebrew, npm, etc.).
`bash`
bun install -g opencode-swarm-plugin@latest
swarm setup
> Note: You can also use npm install -g, but Bun must be installed to run the CLI.
`text`
/plugin
Choose Marketplace β opencode-swarm-plugin β Install.
GitHub marketplace (this repo):
`text`
/plugin marketplace add joelhooks/swarm-tools
/plugin install swarm@swarm-tools
Global install (npm):
`bashnpm install -g opencode-swarm-pluginAfter
`
swarm claude install
Project-local config (standalone):
`bash`
swarm claude init
MCP auto-launch: Claude Code starts MCP servers declared in the plugin mcpServers config automatically. You only need swarm mcp-serve when debugging outside Claude Code.
If Claude Code reports an MCP failure or no swarm tools appear, build artifacts are missing.
1. From the repo root, build the plugin:
`bash`
bun install
bun turbo build --filter=opencode-swarm-plugin
packages/opencode-swarm-plugin/dist/
2. Confirm exists./plugin
3. Reinstall the plugin from and restart OpenCode.
`bash`
cd your-project
swarm init
`bash`Inside OpenCode
/swarm "Add user authentication with OAuth"
What happens:
- Task decomposed into parallel subtasks (coordinator queries past similar tasks)
- Worker agents spawn with file reservations
- Progress tracked with auto-checkpoints at 25/50/75%
- Completion runs bug scans, releases file locks, records learnings
Done. You're swarming.
---
Swarms learn from outcomes. Every completed subtask records what worked and what failed - then injects that wisdom into future prompts.
``
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β SWARM LEARNING LOOP β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β TASK βββββΆβ DECOMPOSEβββββΆβ EXECUTE βββββΆβ COMPLETE β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β² β β β β
β β βΌ βΌ βΌ β
β β βββββββββββββββββββββββββββββββββββββββββββ β
β β β EVENT STORE β β
β β β subtask_outcome, eval_finalized, ... β β
β β βββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β β βΌ β
β β βββββββββββββββββββββββββββββββββββββββββββ β
β β β INSIGHTS LAYER β β
β β β Strategy | File | Pattern insights β β
β β βββββββββββββββββββββββββββββββββββββββββββ β
β β β β
β βββββββββββββββββββββββββββββ β
β (injected into next decomposition) β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
swarm-insights (src/swarm-insights.ts) is the data aggregation layer that queries historical outcomes and semantic memory to provide context-efficient summaries for coordinator and worker agents.
Three insight types:
| Type | What It Tracks | Used By |
|------|----------------|---------|
| StrategyInsight | Success rates by decomposition strategy (file-based, feature-based, risk-based) | Coordinators |
| FileInsight | File-specific failure patterns and gotchas from past subtasks | Workers |
| PatternInsight | Common failure patterns across all subtasks (type errors, timeouts, conflicts) | Coordinators |
``
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β DATA FLOW β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ β
β β Event Store β β Semantic Memory β β Anti-Patterns β β
β β (libSQL) β β (Ollama/FTS) β β (Registry) β β
β ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ β
β β β β β
β βΌ βΌ βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β INSIGHTS AGGREGATION β β
β β β β
β β getStrategyInsights() getFileInsights() getPatternInsights() β β
β β β β β β β
β β ββββββββββββββββββββββββΌβββββββββββββββββββββ β β
β β βΌ β β
β β formatInsightsForPrompt() β β
β β (token-budgeted output) β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βββββββββββββββββββββββββΌββββββββββββββββββββββββ β
β βΌ βΌ βΌ β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ β
β β Coordinator β β Worker β β Worker β β
β β (strategy + β β (file-specific β β (file-specific β β
β β patterns) β β gotchas) β β gotchas) β β
β βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
For coordinators (strategy selection):
`typescript
import { getStrategyInsights, getPatternInsights, formatInsightsForPrompt } from "opencode-swarm-plugin";
const strategies = await getStrategyInsights(swarmMail, task);
// Returns: [{ strategy: "file-based", successRate: 85.5, totalAttempts: 12, recommendation: "..." }]
const patterns = await getPatternInsights(swarmMail);
// Returns: [{ pattern: "type_error", frequency: 5, recommendation: "Add type annotations" }]
const summary = formatInsightsForPrompt({ strategies, patterns }, { maxTokens: 500 });
// Injected into decomposition prompt
`
For workers (file-specific context):
`typescript
import { getFileInsights, formatInsightsForPrompt } from "opencode-swarm-plugin";
const fileInsights = await getFileInsights(swarmMail, ["src/auth.ts", "src/db.ts"]);
// Returns: [{ file: "src/auth.ts", failureCount: 3, lastFailure: "2025-12-20T...", gotchas: [...] }]
const summary = formatInsightsForPrompt({ files: fileInsights }, { maxTokens: 300 });
// Injected into worker prompt
`
Caching (5-minute TTL):
`typescript
import { getCachedInsights, clearInsightsCache } from "opencode-swarm-plugin";
const insights = await getCachedInsights(swarmMail, "strategies:auth-task", async () => ({
strategies: await getStrategyInsights(swarmMail, "add auth"),
}));
clearInsightsCache(); // Force fresh computation
`
| Agent Type | Max Tokens | What's Included |
|------------|------------|-----------------|
| Coordinator | 500 | Top 3 strategies + top 3 patterns |
| Worker | 300 | Top 5 files with gotchas |
Strategy success rates map to recommendations:
| Success Rate | Recommendation |
|--------------|----------------|
| β₯80% | "performing well" |
| 60-79% | "moderate - monitor for issues" |
| 40-59% | "low success - consider alternatives" |
| <40% | "AVOID - high failure rate" |
| Source | What It Provides | Query Pattern |
|--------|------------------|---------------|
| Event Store | subtask_outcome events with strategy, success, files_touched, error_type | SQL aggregation |
| Semantic Memory | File-specific learnings from past debugging | Semantic search (TODO) |
| Anti-Pattern Registry | Patterns with >60% failure rate | Direct lookup |
See swarmtools.ai/docs/insights for full details.
---
`bash`
brew install ollama
ollama serve &
ollama pull mxbai-embed-large
Without Ollama, memory falls back to full-text search (still works, just less semantic).
Queries past AI sessions for similar decompositions:
`bash`
git clone https://github.com/Dicklesworthstone/coding_agent_session_search
cd coding_agent_session_search
pip install -e .
cass index # Run periodically to index new sessions
---
Work items (cells) stored in .hive/ and synced to git. Each cell is a unit of work - think GitHub issue but local-first.
Cell IDs: Project-prefixed for clarity (e.g., swarm-mail-lf2p4u-abc123 not generic bd-xxx)
Parallel agents coordinated via Swarm Mail (message passing + file reservations). Coordinator spawns workers β workers reserve files β do work β report progress β complete with verification.
- Pattern maturity tracks what decomposition strategies work
- Confidence decay fades unreliable patterns (90-day half-life)
- Anti-pattern inversion auto-marks failing approaches to avoid
- Outcome tracking learns from speed, errors, retries
Auto-saves progress at milestones. Survives context death or crashes. Data stored in embedded libSQL (no external DB needed).
When checkpoints happen:
- Auto at 25%, 50%, 75% progress
- Before risky operations (via swarm_checkpoint)
- On errors (captures error context for recovery)
Recovery: swarm_recover(project_key, epic_id) returns full context to resume work.
---
Always-on guidance: Coordinator and worker prompts (plus compaction resumes) include an always-on guidance skill. It sets instruction priority and tool order: swarm plugin tools β Read/Edit β search β Bash. Model defaults differ: GPT-5.2-code prefers strict checklists and minimal output; Opus 4.5 allows brief rationale.
| Tool | Purpose |
| ------------------ | ------------------------------------- |
| hive_create | Create cell with type-safe validation |hive_create_epic
| | Atomic epic + subtasks creation |hive_query
| | Query with filters |hive_update
| | Update status/description/priority |hive_close
| | Close with reason |hive_start
| | Mark in-progress |hive_ready
| | Get next unblocked cell |hive_sync
| | Sync to git |
> Migration Note: beads_ tools still work but show deprecation warnings. Update to hive_ tools.
| Tool | Purpose |
| ------------------------ | -------------------------------- |
| swarmmail_init | Initialize session |swarmmail_send
| | Send message to agents |swarmmail_inbox
| | Fetch inbox (context-safe) |swarmmail_read_message
| | Fetch one message body |swarmmail_reserve
| | Reserve files for exclusive edit |swarmmail_release
| | Release reservations |
| Tool | Purpose |
| ------------------------------ | ----------------------------------------------- |
| swarm_select_strategy | Analyze task, recommend strategy |swarm_decompose
| | Generate decomposition prompt (queries CASS) |swarm_validate_decomposition
| | Validate response, detect conflicts |swarm_subtask_prompt
| | Generate worker agent prompt |swarm_status
| | Get swarm progress by epic ID |swarm_progress
| | Report subtask progress |swarm_complete
| | Complete subtask (releases reservations) |swarm_checkpoint
| | Save progress snapshot (auto at 25/50/75%) |swarm_recover
| | Resume from checkpoint |swarm_review
| | Generate review prompt for coordinator |swarm_review_feedback
| | Send approval/rejection to worker (3-strike) |
Vector embeddings for persistent agent learnings. Uses libSQL native vector support via sqlite-vec extension + Ollama for embeddings.
| Tool | Purpose |
|------|---------|
| semantic-memory_store | Store learnings (with auto-tag/auto-link/entity extraction) |semantic-memory_find
| | Search by semantic similarity |semantic-memory_get
| | Get specific memory by ID |semantic-memory_validate
| | Validate memory accuracy (resets 90-day decay) |semantic-memory_list
| | List stored memories |semantic-memory_remove
| | Delete outdated/incorrect memories |
Wave 1-3 Smart Operations:
`typescript
// Simple store (always adds new)
semantic-memory_store(information="OAuth tokens need 5min buffer before expiry")
// Store with auto-tagging (LLM extracts tags)
semantic-memory_store(
information="OAuth tokens need 5min buffer",
metadata='{"autoTag": true}'
)
// Returns: { id: "mem-abc123", autoTags: { tags: ["auth", "oauth", "tokens"], confidence: 0.85 } }
// Store with auto-linking (links to related memories)
semantic-memory_store(
information="Token refresh race condition fixed",
metadata='{"autoLink": true}'
)
// Returns: { id: "mem-def456", links: [{ memory_id: "mem-abc123", link_type: "related", score: 0.82 }] }
// Store with entity extraction (builds knowledge graph)
semantic-memory_store(
information="Joel prefers TypeScript for Next.js projects",
metadata='{"extractEntities": true}'
)
// Returns: { id: "mem-ghi789", entities: [{ name: "Joel", type: "person" }, { name: "TypeScript", type: "technology" }] }
// Combine all smart features
semantic-memory_store(
information="OAuth tokens need 5min buffer to avoid race conditions",
metadata='{"autoTag": true, "autoLink": true, "extractEntities": true}'
)
// Search memories
semantic-memory_find(query="token refresh issues", limit=5)
// Validate memory (resets 90-day decay timer)
semantic-memory_validate(id="mem-abc123")
`
Graceful Degradation: All smart operations fall back to heuristics if LLM/Ollama unavailable:
- Auto-tagging returns undefined (no tags added)undefined
- Auto-linking returns (no links created)
- Entity extraction returns empty arrays
- Vector search falls back to full-text search (FTS5)
Requires Ollama for smart operations:
`bash`
brew install ollama
ollama serve &
ollama pull mxbai-embed-large
See swarm-mail README for full API details.
| Tool | Purpose |
| --------------- | ----------------------- |
| skills_list | List available skills |skills_use
| | Load skill into context |skills_read
| | Read skill content |skills_create
| | Create new skill |
Bundled skills:
- testing-patterns - 25 dependency-breaking techniques, characterization tests
- swarm-coordination - Multi-agent decomposition, file reservations
- cli-builder - Argument parsing, help text, subcommands
- system-design - Architecture decisions, module boundaries
- learning-systems - Confidence decay, pattern maturity
- skill-creator - Meta-skill for creating new skills
---
- Pino logging infrastructure - Structured JSON logs with daily rotation to ~/.config/swarm-tools/logs/swarm log
- Compaction hook instrumented - 14 log points across all phases (START, GATHER, RENDER, DECIDE, COMPLETE)
- CLI - Query/tail logs with module, level, and time filters
- Analytics queries - 5 pre-built queries based on Four Golden Signals (latency, traffic, errors, saturation, conflicts)
- libSQL storage (embedded SQLite) replaced PGLite - no external DB needed
- 95% integration test coverage - checkpoint/recovery proven with 9 tests
- Coordinator review gate - swarm_review + swarm_review_feedback with 3-strike rulemjhgw0g
- Smart ID resolution - partial hashes work like git ( matches opencode-swarm-monorepo-lf2p4u-mjhgw0ggt00)hive_sync
- Auto-sync at key events - no more forgotten callsswarm-mail-xxx
- Project-prefixed cell IDs - instead of generic bd-xxx
---
Built on swarm-mail event sourcing primitives. Data stored in libSQL (embedded SQLite).
``
src/
βββ hive.ts # Work item tracking integration
βββ swarm-mail.ts # Agent coordination tools
βββ swarm-orchestrate.ts # Coordinator logic (spawns workers)
βββ swarm-decompose.ts # Task decomposition strategies
βββ swarm-insights.ts # Historical insights aggregation (strategy/file/pattern)
βββ swarm-review.ts # Review gate for completed work
βββ skills.ts # Knowledge injection system
βββ learning.ts # Pattern maturity, outcomes
βββ anti-patterns.ts # Anti-pattern detection
βββ structured.ts # JSON parsing utilities
βββ schemas/ # Zod validation schemas
---
`bashFrom monorepo root
bun turbo build --filter=opencode-swarm-plugin
bun turbo test --filter=opencode-swarm-plugin
bun turbo typecheck --filter=opencode-swarm-plugin
$3
Create changeset files manually (avoid
bunx changeset).`bash
From monorepo root
cat > .changeset/your-change.md << 'EOF'
---
"opencode-swarm-plugin": patch
---Describe the change
EOF
git add .changeset/your-change.md
git commit -m "chore: add changeset"
git push
`Changesets CI opens a release PR. Merge it to publish via npm OIDC.
$3
Test decomposition quality and coordinator discipline with Evalite (TypeScript-native eval framework):
`bash
Run all evals
bun run eval:runRun specific suites
bun run eval:decomposition # Task decomposition quality
bun run eval:coordinator # Coordinator protocol compliance
bun run eval:compaction # Compaction prompt qualityCheck eval status (progressive gates)
swarm eval status [eval-name]View history with trends
swarm eval history
`Progressive Gates:
`
Phase Runs Gate Behavior
ββββββββββββββββββββββββββββββββββββββββββββββββββ
Bootstrap <10 β
Always pass (collect data)
Stabilization 10-50 β οΈ Warn on >10% regression
Production >50 β Fail on >5% regression
`What gets evaluated:
| Eval Suite | Measures | Data Source |
| --------------------- | ------------------------------------------------------------- | ------------------------------------------------ |
|
swarm-decomposition | Subtask independence, complexity balance, coverage, clarity | Fixtures + .opencode/eval-data.jsonl |
| coordinator-session | Violation count, spawn efficiency, review thoroughness | ~/.config/swarm-tools/sessions/*.jsonl |
| compaction-prompt | ID specificity, actionability, identity, forbidden tools | Session compaction events |Learning Feedback Loop:
When eval scores drop >15% from baseline, failure context is automatically stored to semantic memory. Future prompts query these learnings for context.
Data capture locations:
- Decomposition inputs/outputs:
.opencode/eval-data.jsonl
- Eval history: .opencode/eval-history.jsonl
- Coordinator sessions: ~/.config/swarm-tools/sessions/*.jsonl
- Subtask outcomes: swarm-mail databaseSee evals/README.md for full architecture, scorer details, CI integration, and how to write new evals.
$3
Clean test session files:
`bash
Remove test session files from global sessions directory
./scripts/clean-test-sessions.shDry run (see what would be deleted)
./scripts/clean-test-sessions.sh --dry-run
`Test session files (
test.jsonl, no-context.jsonl, timing-test*.jsonl) accumulate in ~/.config/swarm-tools/sessions/ during development. Run this script periodically to clean them up.---
CLI Reference
$3
`bash
swarm setup # Interactive installer for all dependencies
swarm setup -y # Non-interactive mode (auto-migrate stray databases)
swarm doctor # Check dependency health (CASS, UBS, Ollama)
swarm init # Initialize hive in current project
swarm config # Show config file paths
swarm update # Update swarm plugin and bundled skills
swarm migrate # Migrate from legacy PGLite to libSQL
swarm version # Show version info
`Database Consolidation:
swarm setup automatically detects and migrates stray databases (.opencode/swarm.db, .hive/swarm-mail.db, nested package databases) to the global database at ~/.config/swarm-tools/swarm.db. Use -y flag to migrate without prompting.$3
swarm query - SQL analytics with presets
`bash
Execute custom SQL query against event store
swarm query --sql "SELECT * FROM events WHERE type='worker_spawned' LIMIT 10"Use preset query (10+ presets available)
swarm query --preset failed_decompositions
swarm query --preset duration_by_strategy
swarm query --preset file_conflicts
swarm query --preset worker_success_rate
swarm query --preset review_rejections
swarm query --preset blocked_tasks
swarm query --preset agent_activity
swarm query --preset event_frequency
swarm query --preset error_patterns
swarm query --preset compaction_statsOutput formats
swarm query --preset failed_decompositions --format table # Default
swarm query --preset duration_by_strategy --format csv
swarm query --preset file_conflicts --format json
`swarm dashboard - Live terminal UI
`bash
Launch dashboard (auto-refresh every 1s)
swarm dashboardFocus on specific epic
swarm dashboard --epic mjmas3zxlmgCustom refresh rate (milliseconds)
swarm dashboard --refresh 2000
`Dashboard shows:
- Active workers and their current tasks
- Progress bars for in-progress work
- File reservations (who owns what)
- Recent messages between agents
- Error alerts
swarm replay - Event replay with timing
`bash
Replay epic at normal speed
swarm replay mjmas3zxlmgFast playback
swarm replay mjmas3zxlmg --speed 2x
swarm replay mjmas3zxlmg --speed instantFilter by event type
swarm replay mjmas3zxlmg --type worker_spawned,task_completedFilter by agent
swarm replay mjmas3zxlmg --agent DarkHawkTime range filters
swarm replay mjmas3zxlmg --since "2025-12-25T10:00:00"
swarm replay mjmas3zxlmg --until "2025-12-25T12:00:00"Combine filters
swarm replay mjmas3zxlmg --speed 2x --type worker_spawned --agent BlueLake
`swarm export - Data export for analysis
`bash
Export all events as JSON (stdout)
swarm exportExport specific epic
swarm export --epic mjmas3zxlmgExport formats
swarm export --format json --output events.json
swarm export --format csv --output events.csv
swarm export --format otlp --output events.otlp # OpenTelemetry ProtocolPipe to jq for filtering
swarm export --format json | jq '.[] | select(.type=="worker_spawned")'
`swarm stats - Health metrics
`bash
Last 7 days (default)
swarm statsCustom time period
swarm stats --since 24h
swarm stats --since 30mJSON output for scripting
swarm stats --json
`swarm history - Activity timeline
`bash
Last 10 swarms (default)
swarm historyMore results
swarm history --limit 20Filter by status
swarm history --status success
swarm history --status failed
swarm history --status in_progressFilter by strategy
swarm history --strategy file-based
swarm history --strategy feature-basedVerbose mode (show subtasks)
swarm history --verbose
`swarm log - Query/tail logs
`bash
Recent logs (last 50 lines)
swarm logFilter by module
swarm log compactionFilter by level
swarm log --level error
swarm log --level warnTime filters
swarm log --since 30s
swarm log --since 5m
swarm log --since 2hJSON output
swarm log --jsonLimit output
swarm log --limit 100Watch mode (live tail)
swarm log --watch
swarm log --watch --interval 500 # Poll every 500ms
`swarm log sessions - View coordinator sessions
`bash
List all sessions
swarm log sessionsView specific session
swarm log sessions Most recent session
swarm log sessions --latestFilter by event type
swarm log sessions --type DECISION
swarm log sessions --type VIOLATION
swarm log sessions --type OUTCOME
swarm log sessions --type COMPACTIONJSON output for jq
swarm log sessions --json
`$3
Use
DEBUG env var to enable swarm debug logs:`bash
All swarm logs
DEBUG=swarm:* swarm dashboardCoordinator only
DEBUG=swarm:coordinator swarm replay Workers only
DEBUG=swarm:worker swarm exportSwarm mail only
DEBUG=swarm:mail swarm query --preset agent_activityMultiple namespaces (comma-separated)
DEBUG=swarm:coordinator,swarm:worker swarm dashboard
`Namespaces:
| Namespace | What It Logs |
|-----------|--------------|
|
swarm:* | All swarm activity |
| swarm:coordinator | Coordinator decisions (spawn, review, approve/reject) |
| swarm:worker | Worker progress, reservations, completions |
| swarm:mail | Inter-agent messages, inbox/outbox activity |Observability Architecture
Swarm uses event sourcing for complete observability. Every coordination action is an event - nothing is lost, everything is queryable.
`
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β OBSERVABILITY FLOW β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββ β
β β Agent β swarmmail_init() β
β β (Worker) β swarmmail_reserve(paths=["src/auth.ts"]) β
β β β swarm_progress(status="in_progress") β
β β β swarm_complete(...) β
β βββββββ¬βββββββ β
β β β
β βΌ β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β libSQL Event Store β β
β β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β events table (append-only) β β β
β β β ββ id, type, timestamp, project_key, data β β β
β β β ββ agent_registered, message_sent, ... β β β
β β β ββ task_started, task_progress, task_completed β β β
β β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β β
β β Automatic Projections (materialized views): β β
β β ββ agents (who's registered) β β
β β ββ messages (agent inbox/outbox) β β
β β ββ reservations (file locks) β β
β β ββ swarm_contexts (checkpoints) β β
β βββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ β
β β β
β ββββββββββββββΌβββββββββββββ¬βββββββββββββ β
β βΌ βΌ βΌ βΌ β
β βββββββββββ βββββββββββ ββββββββββββ ββββββββββββ β
β β swarm β β swarm β β swarm β β swarm β β
β β query β β stats β β dashboardβ β replay β β
β β (SQL) β β (counts)β β (TUI) β β (time) β β
β βββββββββββ βββββββββββ ββββββββββββ ββββββββββββ β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Analytics Layer (Golden Signals) β β
β β ββ Latency: avg task duration, P50/P95/P99 β β
β β ββ Traffic: events/sec, message rate β β
β β ββ Errors: task failures, violations β β
β β ββ Saturation: file conflicts, blocked tasks β β
β β ββ Conflicts: reservation collisions, deadlocks β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
`$3
Agent Lifecycle:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
agent_registered | Agent calls swarmmail_init() | Agent discovery, project tracking |
| agent_active | Periodic heartbeat | Last-seen tracking |Messages:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
message_sent | Agent sends swarm mail | Coordination, thread tracking |
| message_read | Agent reads message | Read receipts |
| message_acked | Agent acknowledges | Confirmation tracking |
| thread_created | First message in thread | Thread lifecycle |
| thread_activity | Thread stats update | Unread counts, participants |File Reservations:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
file_reserved | Agent reserves files | Conflict detection, lock management |
| file_released | Agent releases files | Lock cleanup, reservation tracking |
| file_conflict | Reservation collision | Conflict resolution, deadlock detection |Task Tracking:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
task_started | Agent starts cell work | Progress tracking, timeline |
| task_progress | Agent reports milestone | Real-time monitoring, ETA |
| task_completed | Agent calls swarm_complete() | Outcome tracking, learning signals |
| task_blocked | Agent hits blocker | Dependency tracking, alerts |Swarm Coordination:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
swarm_started | Coordinator begins epic | Swarm lifecycle tracking |
| worker_spawned | Coordinator spawns worker | Worker tracking, spawn order |
| worker_completed | Worker finishes subtask | Outcome tracking, duration |
| review_started | Coordinator begins review | Review tracking, attempts |
| review_completed | Review finishes | Approval/rejection tracking |
| swarm_completed | All subtasks done | Epic completion, success rate |
| decomposition_generated | Task decomposed | Strategy tracking, subtask planning |
| subtask_outcome | Subtask finishes | Learning signals, scope violations |Checkpoints & Recovery:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
swarm_checkpointed | Auto at 25/50/75% or manual | Recovery, context preservation |
| swarm_recovered | Resume from checkpoint | Recovery tracking, checkpoint age |
| checkpoint_created | Checkpoint saved | Checkpoint lifecycle |
| context_compacted | Context compaction runs | Context compression tracking |Validation & Learning:
| Event Type | When It Fires | Used For |
|------------|---------------|----------|
|
validation_started | Validation begins | Validation lifecycle |
| validation_issue | Validation finds issue | Issue tracking, debugging |
| validation_completed | Validation finishes | Pass/fail tracking |
| human_feedback | Human accepts/modifies | Human-in-loop learning |Full Schema: See swarm-mail/src/streams/events.ts for complete Zod schemas (30+ event types)
$3
Pre-built queries based on Four Golden Signals observability framework:
Latency (how fast):
`sql
-- Average task duration by type
SELECT
json_extract(data, '$.type') as task_type,
AVG(duration_ms) as avg_duration,
MAX(duration_ms) as p99_duration
FROM events
WHERE type = 'task_completed'
GROUP BY task_type;
`Traffic (how much):
`sql
-- Events per hour
SELECT
strftime('%Y-%m-%d %H:00', datetime(timestamp/1000, 'unixepoch')) as hour,
COUNT(*) as event_count
FROM events
GROUP BY hour
ORDER BY hour DESC
LIMIT 24;
`Errors (what's broken):
`sql
-- Failed tasks with reasons
SELECT
json_extract(data, '$.bead_id') as task,
json_extract(data, '$.reason') as failure_reason,
timestamp
FROM events
WHERE type = 'task_completed'
AND json_extract(data, '$.success') = 0
ORDER BY timestamp DESC;
`Saturation (resource contention):
`sql
-- File reservation conflicts
SELECT
json_extract(data, '$.paths') as file_paths,
COUNT(*) as conflict_count,
GROUP_CONCAT(json_extract(data, '$.agent_name')) as agents
FROM events
WHERE type = 'file_reserved'
GROUP BY file_paths
HAVING COUNT(*) > 1;
`Conflicts (deadlocks, collisions):
`sql
-- Reservation wait times (TTL expirations)
SELECT
json_extract(data, '$.agent_name') as agent,
json_extract(data, '$.paths') as paths,
(expires_at - timestamp) as wait_time_ms
FROM events
WHERE type = 'file_reserved'
AND (expires_at - timestamp) > 10000 -- >10sec wait
ORDER BY wait_time_ms DESC;
`Run these via:
`bash
swarm query --preset golden-signals
swarm query --preset compaction-health
swarm query --preset file-conflicts
`$3
Scenario 1: Task is stuck "in_progress" forever
`bash
1. Find the task in events
swarm query --sql "SELECT * FROM events WHERE json_extract(data, '$.bead_id') = 'mjmas411jtj' ORDER BY timestamp"2. Check for file reservation conflicts
swarm query --preset file_conflicts3. Replay to see execution timeline
swarm replay mjmas3zxlmg --agent WorkerName4. Check if agent is still registered
swarm stats5. Enable debug logging for live tracking
DEBUG=swarm:worker swarm dashboard --epic mjmas3zxlmg
`Scenario 2: High failure rate for a specific epic
`bash
1. Get stats by epic
swarm query --sql "SELECT type, COUNT(*) FROM events WHERE json_extract(data, '$.epic_id') = 'mjmas3zxlmg' GROUP BY type"2. Find failures with reasons
swarm query --sql "SELECT * FROM events WHERE type = 'task_completed' AND json_extract(data, '$.epic_id') = 'mjmas3zxlmg' AND json_extract(data, '$.success') = 0"3. Export for analysis
swarm export --epic mjmas3zxlmg --format csv > failures.csv4. Check coordinator session for violations
swarm log sessions --type VIOLATION --json
`Scenario 3: Performance regression (tasks slower than before)
`bash
1. Check latency trends
swarm query --preset duration_by_strategy2. Compare with historical baselines
swarm history --limit 503. Identify bottlenecks
swarm dashboard --epic mjmas3zxlmg --refresh 24. Analyze worker spawn efficiency
swarm query --preset worker_success_rate
`Scenario 4: File reservation conflicts
`bash
1. Check active locks
swarm query --preset file_conflicts2. See who's holding what
swarm dashboard # Shows file locks section3. View full conflict history
swarm query --sql "SELECT * FROM events WHERE type = 'file_conflict' ORDER BY timestamp DESC LIMIT 20"4. Replay to see conflict sequence
swarm replay mjmas3zxlmg --type file_reserved,file_released,file_conflict
`Scenario 5: Coordinator not spawning workers
`bash
1. Check coordinator session for violations
swarm log sessions --latest --type DECISION,VIOLATION2. Verify decomposition was generated
swarm query --sql "SELECT * FROM events WHERE type = 'decomposition_generated' ORDER BY timestamp DESC LIMIT 5"3. Debug coordinator logic
DEBUG=swarm:coordinator swarm replay mjmas3zxlmg4. Check for blocked tasks
swarm query --preset blocked_tasks
`$3
`sql
CREATE TABLE events (
id INTEGER PRIMARY KEY AUTOINCREMENT,
type TEXT NOT NULL, -- Event discriminator
project_key TEXT NOT NULL, -- Project path (for multi-project filtering)
timestamp INTEGER NOT NULL, -- Unix ms
sequence INTEGER GENERATED ALWAYS AS (id) STORED,
data TEXT NOT NULL, -- JSON payload (event-specific fields)
created_at TEXT DEFAULT (datetime('now'))
);-- Indexes for fast queries
CREATE INDEX idx_events_project_key ON events(project_key);
CREATE INDEX idx_events_type ON events(type);
CREATE INDEX idx_events_timestamp ON events(timestamp);
CREATE INDEX idx_events_project_type ON events(project_key, type);
`Event payload examples:
`json
// agent_registered event
{
"type": "agent_registered",
"project_key": "/path/to/project",
"timestamp": 1703001234567,
"data": "{\"agent_name\":\"BlueLake\",\"program\":\"opencode\",\"model\":\"claude-sonnet-4\",\"task_description\":\"mjmas411jtj: Update READMEs\"}"
}// task_completed event
{
"type": "task_completed",
"project_key": "/path/to/project",
"timestamp": 1703001299999,
"data": "{\"agent_name\":\"BlueLake\",\"bead_id\":\"mjmas411jtj\",\"summary\":\"Updated both READMEs with CLI reference and event schema\",\"files_touched\":[\"packages/opencode-swarm-plugin/README.md\",\"packages/swarm-mail/README.md\"],\"success\":true}"
}
`$3
`bash
libSQL database path
~/.config/swarm-tools/libsql//swarm.dbFind your project's database
swarm config # Shows database path for current project
``---
- Full Docs - Deep dives, patterns, best practices
- swarm-mail Package - Event sourcing primitives, database layer
- AGENTS.md - Monorepo guide, testing strategy, TDD workflow
> "High-variability sequencing of whole-task problems."
> β 4C/ID Instructional Design Model
---
MIT