swarm 0.1 one goal in
swarm out

v0.1.0 / mit
opencode 2.x · v1 fallback
default model deepseek v4.1 flash
ready to spawn

A supervised multi-agent runtime for OpenCode. One goal goes in, a plan comes out, and workers run in parallel without ever overwriting each other.

start-here/

two commands · no build step
Get started↗
01 / the cast

roles/

Seven roles, one runtime. Each spawn is a real child session with its own model, brief, and file write-set. Read it like a running order.

01 orchestrator deepseek-v4.1-flash Plans the board, spawns workers, reviews only escalations, closes with evidence.
02 worker deepseek-v4.1-flash Owns a task and a write-set. Claims files, edits, tests, and reports back.
03 tester deepseek-v4.1-flash Runs the commands, checks the acceptance criteria, writes the proof.
04 scout flash #low Read-only reconnaissance. Maps the repo before anyone touches it.
05 reviewer flash #high Reads the diff against the plan. Approves, or sends it back with reasons.
06 planner flash #high Turns a vague goal into tasks with disjoint write-sets and dependencies.
07 integrator flash #high Runs the full gate, resolves the seams, and prepares the final summary.
sorted by depth · 7 roles
02 / setup

install/

One path, three steps. The config never changes — only the file you drop it into. Global puts the swarm in every chat; project scopes it to one repo.

opencode 2.x bun 1.4+ model any tool-capable node 20+ for the example license mit
01 clone ~1 min
terminal 
git clone https://github.com/DumDuky/opencode-swarm.git
cd opencode-swarm
bun install
02 add the plugin one entry
~/.config/opencode/opencode.json
opencode.json 
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    { "package": "/absolute/path/to/opencode-swarm",
      "options": {} }
  ],
  "instructions": [
    "/absolute/path/to/opencode-swarm/docs/SWARM.md"
  ]
}

Every chat, every project. This is the recommended one.

03 reload and run one goal
terminal 
opencode reload
opencode plugin list   # shows opencode-swarm
/swarm Add a health endpoint with tests
03 / the hard part

no-lost-updates/

Parallel agents are easy to demo and hard to trust. Three layers keep the workspace consistent, and a fourth keeps the bill honest.

Swarm architecture: orchestrator over a task board, message bus, file leases, and supervisor, with workers below
fig. 01 — control plane over shared state
partition
Plan-time write-sets. Overlapping open tasks are rejected unless a dependency orders them.
leases
Claim before edit. File and directory leases conflict correctly, and expire on a TTL.
hashes
Stale writes fail. If the file changed since the last read, the edit is refused and must re-read.
budget
Cost is the guard. Warn, then pause. Member, depth, and concurrency caps are separate.
same-file edits serialize by design · worktrees are next
04 / receipts

proof/

Real runs, not screenshots. Every number below comes from the repo's test suite and its recorded swarm runs.

Two workers, one dependency gate, zero overwrites. The tester spawned only after both were done — and the orchestrator re-ran the commands before closing the swarm.
52
tests passing
0
lost updates
$3.00
default budget
3/3
tasks · health run
05 / dependencies

built-with/

Small surface, boring dependencies. The core talks to a narrow runtime interface, so it stays testable.

◆OpenCode
◆Bun
◆TypeScript
◆Zod
◆DeepSeek
◆GitHub Actions
06 / the interface

surface-area/

Five commands, ten tools, five config groups. That is the whole API you have to remember.

commands/

5 · typed in chat
/swarm <goal>start or resume
/swarm-statusboard, leases, budget
/swarm-stopstop and interrupt
/swarm-approveallow an escalation
/swarm-denyrefuse an escalation

tools/

10 · called by agents
swarm_taskplan and claim
swarm_spawnstart a member
swarm_messagetalk to peers
swarm_fileslease files
swarm_waitjoin results
swarm_finishclose with proof
swarm_reviewapproval queue

config/

5 · one json block
modelsper-role, or inherit
limitsmembers, depth, rate
budgetwarn, pause, hard stop
leasesttl, auto-claim
approvalbalanced, strict, permissive
07 / before you ask

questions/

The honest answers, including the parts that are still missing.

installDo I need OpenCode Go?+

No. Any tool-capable provider works. DeepSeek V4.1 Flash on OpenCode Go is only the default because it is cheap and fast at this task shape. Set models.orchestrator to "inherit" to follow whatever model you picked with /models.

safetyCan two workers edit the same file?+

Not concurrently. The board rejects overlapping write-sets at plan time, leases serialize whatever still collides, and the content-hash guard refuses a write when the file changed underneath the worker.

costWhat stops a runaway swarm?+

A cost budget with warn and pause thresholds, plus member, depth, concurrency, and message-rate caps. /swarm-stop interrupts everything immediately. The budget is tracked per swarm, not per session.

autonomyDoes it run forever on its own?+

No. It is goal-driven, not a daemon. It stops when the board is done, when you stop it, when the budget is hit, or when a limit is exceeded. It will not invent new goals.

limitsIs it a sandbox?+

No, and you should not treat it as one. Workers run with the permissions OpenCode gives them. Destructive shell commands are blocked or escalated, but interpreters and repo content are still dangerous. Point it at repositories you trust.

roadmapWhat is still missing?+

Worktree isolation and a merge queue, a TUI dashboard for live state, an npm package, and richer plan validation. The current model is a shared workspace with leases, which is safe but serializes same-file edits. See the roadmap.

08 / your turn

run-it/

Clone it, add one entry, reload. Then give it a goal and watch the board fill up. No account, no telemetry, no build step.

one command 
/swarm Add a health endpoint with tests
● plans · spawns · leases · verifies · closes
Star on GitHub ↗ Read the docs ↗