Quickstart

Multi-agent coordination for your codebase. Install, setup, /swarm your first task.

What you get: Parallel worker agents, automatic file locking, persistent learning, git-backed work tracking.

Install

npm install -g opencode-swarm-plugin@latest

Or with Bun:

bun add -g opencode-swarm-plugin@latest

Prerequisites: Node.js 18+, OpenCode CLI, git repository

Setup

swarm setup

Expected output:

✓ Migrating from PGLite to libSQL...
✓ OpenCode plugin configured
✓ Hive initialized at .hive/
✓ All systems ready

This handles migrations automatically, configures the OpenCode plugin, and initializes the hive (git-backed work tracker).

Check health:

swarm doctor

✓ OpenCode plugin configured
✓ Hive storage: libSQL (embedded SQLite)
✓ Semantic memory: ready
✓ Dependencies: all installed

Your First Swarm

In OpenCode:

/swarm "Add a health check endpoint at /api/health"

What happens:

Analyzing task...
Decomposing into 2 subtasks:
  1. Create /api/health endpoint
  2. Add health check test

Creating epic: bd-abc123
  ├─ bd-abc123.1 (worker-1)
  └─ bd-abc123.2 (worker-2)

Spawning 2 worker agents...

[worker-1] Reserved: src/api/health.ts
[worker-1] ✓ Created endpoint
[worker-2] Reserved: src/api/health.test.ts
[worker-2] ✓ Added tests

✓ All subtasks complete
✓ UBS scan: 0 issues
✓ Synced to git

Files created:

src/api/health.ts - endpoint implementation
src/api/health.test.ts - test coverage
.hive/issues.jsonl - work tracking (git-committed)

How Swarm Works

Decompose - Break task into parallel subtasks
Reserve - Each worker locks their files (no conflicts)
Execute - Workers run in parallel, report progress
Verify - UBS bug scan, type check, test run
Complete - Release locks, sync to git, store learnings

Optional: Vector Search

For semantic memory (search learnings by meaning, not keywords):

brew install ollama
ollama serve &
ollama pull mxbai-embed-large

Without Ollama: Falls back to full-text search. Everything still works.

Key Tools (For Manual Control)

Most work happens via /swarm, but you can drive manually:

Tool	Purpose
`hive_ready()`	Get next unblocked task
`hive_create()`	Create new work item
`hive_sync()`	Sync to git (MANDATORY at session end)
`swarmmail_init()`	Initialize coordination for multi-agent work
`swarmmail_reserve()`	Lock files before editing
`swarm_complete()`	Finish task + cleanup
`skills_use()`	Load domain expertise (testing, CLI building, etc)
`semantic-memory_store()`	Store learnings for future sessions
`semantic-memory_find()`	Search past learnings by meaning

Using Semantic Memory

// After solving a tricky bug
semantic-memory_store({
  information: "OAuth refresh tokens need 5min buffer before expiry to avoid race conditions. Implemented with: if (expiresAt - Date.now() < 300000) refresh()",
  tags: "auth,tokens,race-conditions"
})

// Before starting similar work
semantic-memory_find({
  query: "token refresh race conditions",
  limit: 5
})

Memories persist across sessions. 90-day decay keeps knowledge fresh.

Using Skills

Pre-built expertise packages:

skills_list() // See available skills
skills_use({ name: "testing-patterns" }) // Load Feathers' dependency-breaking techniques
skills_use({ name: "swarm-coordination" }) // Multi-agent orchestration patterns

Bundled skills: testing-patterns, swarm-coordination, cli-builder, system-design

CLI Commands

Command	Purpose
`swarm setup`	Initial configuration (run once)
`swarm doctor`	Check dependencies and health
`swarm init`	Initialize hive in new project
`swarm config`	Show config paths

What's Next

OpenCode Plugin Reference - All 40+ tools documented
Philosophy - Design principles and mental models
Patterns - Coordination patterns and best practices
Swarm Mail Architecture - Event sourcing deep dive
Semantic Memory - Persistent agent learning

Troubleshooting

"swarmmail_init failed"

Ensure you're in a git repository
Check .opencode/ directory is writable

"Plugin not loading"

swarm setup  # Re-run setup
swarm doctor # Check what's missing

Migrations stuck

swarm setup auto-migrates PGLite → libSQL
Check .hive/ directory permissions
Run swarm doctor to verify storage

Session Checklist

Every session:

Start: hive_ready() - What's next?
Work: /swarm for parallel tasks OR use tools manually
End: hive_sync() + git push - The plane is not landed until git push succeeds

That's it. Install, setup, /swarm. Ship it.

Quickstart

On this page