opencode-swarm: an architect-led gate between AI-written code and your main branch
Architect-centric agentic swarm plugin for OpenCode. Hub-and-spoke orchestration with SME consultation, code generation, and QA review.
At a glance
- What is it?
- OpenCode Swarm is an MIT-licensed TypeScript plugin that splits a single OpenCode coding session into separate planner, coder, reviewer, test engineer and security roles, and refuses to let a change through until the required gates pass. Its value depends on one condition: the active agent has to be a Swarm architect, or the whole pipeline is bypassed.
- Who is it for?
- Adopt Swarm if you already run OpenCode and want review, test and security passes to be separate agents from the one that wrote the code, and you accept that every one of those passes costs tokens. Skip it if you want a drop-in tool that works regardless of which agent is active, or if you cannot tolerate a pipeline that silently does nothing when the wrong agent is selected.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The trust gap Swarm is built to close
The README frames the problem in one line: closing the gap between the model saying it is done and the code actually working. That is a real failure mode for anyone who has accepted an AI patch, run the test suite, and watched it fail. The usual cause is structural. One model writes the code and the same model, in the same session, with the same context, decides the code is fine. Swarm's answer is to stop asking the author to grade its own work. Planning, implementation, review, testing and documentation become separate internal roles, and the README states that nothing ships until every required gate passes. The intended user is an engineer already running OpenCode who wants a second and third opinion generated mechanically rather than remembered to be run. It is not aimed at people who want a single prompt-and-patch loop, and the free tier note about OpenCode Zen's model roster suggests the project expects cost-sensitive users to start there.
Hub-and-spoke: one architect, many bounded roles
The architecture is a hub with spokes. A single Swarm architect coordinates the internal agents, and the README is explicit that you never manually switch between internal roles. The roster is long and tiered: architect, coder, reviewer, test_engineer, critic, critic_finding_validator, explorer, sme, docs, designer, critic_oversight, critic_sounding_board, critic_drift_verifier, critic_hallucination_verifier, curator_init, curator_phase, council_generalist, council_skeptic and council_domain_expert. The README also warns that this list is not the source of truth and that /swarm agents prints the live roster generated from current plugin configuration. That warning matters more than it looks. Because roles are conditional and configuration-driven, a roster you read in a README can drift from the roster your install actually runs. The design constraint that shapes everything else is gated execution: agents never mutate the codebase in parallel. State lives in .swarm/, which is what makes sessions resumable across days. A separate auto-review engine runs a bounded whole-diff review in a fresh read-only model session and produces structured findings anchored to diff lines. Fresh session and read-only are the two properties doing the work here, since an author agent's context is exactly the context you want the reviewer not to share.
Installing it, and the file it edits on your behalf
The documented install is one command: bunx opencode-swarm install. It requires Bun >= 1.3.13, checked with bun --version, or Node.js >= 22.13 for npm installs, where the Node-hosted sidecar uses the built-in node:sqlite module. The npm path is npm install -g opencode-swarm followed by opencode-swarm install. The README states what that single command does: installs the package, registers it as an OpenCode plugin, disables conflicting default agents, and writes a ready-to-edit config at ~/.config/opencode/opencode-swarm.json. The first-run note adds detail that deserves attention before you run it. The installer registers the plugin, writes the global plugin config, creates a project override when missing, and disables the native explore and general agents in opencode.json. That is a modification to your existing OpenCode configuration, made without a prompt, and it is the kind of thing worth reviewing in version control afterwards. Configuration keys visible in the material include external_skills.curation_enabled (disabled by default), skill_opt.enabled (default false) and pr_monitor.enabled (opt-in). The README also states that any agent's model can be overridden and any agent disabled.
The bypass condition you have to understand first
This is the sharpest edge in the project and the README says it twice. If the active OpenCode agent is not a Swarm architect, the plugin workflow is bypassed. The first-run note repeats it: if you are not using a Swarm architect, the Swarm gates, reviewers and test agents are bypassed. Read that against the marketing line about nothing shipping until every gate passes. The gates are real, but they are conditional on an agent selection you make, and the failure is silent. You get a normal OpenCode session that looks like it is working, with no reviewers and no test engineer, and nothing in the README describes a warning when that happens. The documented remedy is manual: open the OpenCode agent or mode picker and choose the Swarm architect when needed. For a tool whose entire pitch is enforced verification, relying on the user to pick the right agent from a picker is the weakest link in the chain. Treat the bypass as a design trade-off rather than a bug, but treat it as the first thing to test in your own setup.
Guardrails: scope enforcement and shell write detection
Two guardrail mechanisms are described in enough detail to assess. Scope enforcement validates write targets against a declared scope, with cross-process persistence, TTL expiry, and blocking of scope-aware destructive commands. The README specifically notes that it handles both single-string and array-based path arguments, naming files[], paths[] and targetFiles[], to prevent scope bypass through multi-file tool calls. That is a concrete adversarial case: an agent that cannot write outside scope with one path might try to smuggle extra paths through an array argument, and the guardrail is written to catch it. The second mechanism is shell write detection, described as static analysis of POSIX, PowerShell and cmd commands to detect file writes before execution, covering redirects, builtins, in-place editors, network downloads, archive extraction and destructive git operations. Static analysis of shell strings is an inherently approximate approach, and the README does not claim otherwise, but it is the right layer for the problem: an agent that cannot write a file directly can still curl one down or redirect output into it. Built-in security is listed as SAST, secrets scanning and dependency audit per task.
Opt-in pipelines and what their defaults tell you
Several subsystems are off by default, and the defaults are informative. External skill curation is disabled unless external_skills.curation_enabled is set to true, and it exposes seven tools: external_skill_discover, external_skill_list, external_skill_inspect, external_skill_promote, external_skill_reject, external_skill_delete and external_skill_revoke. Candidates pass three gates before evaluation: a prompt injection scan with 12 regex patterns, an unsafe instruction scan with 25 patterns, and a provenance integrity check covering SHA-256, timestamp, URL, publisher and hash verification. A project that ships a quarantine and promotion pipeline for third-party skills, and leaves it off, is telling you it does not yet trust that pipeline by default. The same pattern appears in the skill optimizer, a single-skill tool driven by /swarm skill-opt plan|run|status|diff|approve|reject|rollback|history, which is bounded, restartable and reversible, cannot mutate source, harness or security surfaces, and is disabled by default. The auto-review engine follows suit: v7 is opt-in, and the README states v8's default is pinned to a committed 30-diff cost burn-in. That phrase is the most useful sentence in the document. It admits that review passes have a measurable token cost and that the default was set by measuring it.
Where it is the wrong tool, and what to use instead
The clearest wrong-tool case is a team that wants verification to be unconditional. Swarm cannot give you that, because the pipeline is bypassed whenever the active agent is not a Swarm architect. If your workflow switches agents for other reasons, or you drive OpenCode programmatically without selecting an agent, you will get the bypass path and possibly not notice. A second case is a solo developer on a tight budget doing small edits. The multi-role pipeline multiplies model calls per change, and the 30-diff burn-in reference confirms the project treats that cost as a real constraint rather than a rounding error. A third case is non-GitHub hosting. The gated GitHub Action, swarm-implement.yml, is triggered by the swarm:implement issue label or workflow_dispatch and opens an evidence PR, and the PR Monitor polls through the gh CLI, so a GitLab or self-hosted workflow loses that surface. The obvious alternative is a single-agent coding assistant with a self-review step, which is what most tools ship. The difference in approach is not the number of prompts; it is that Swarm runs the reviewer in a fresh read-only session against the whole diff, so the reviewer does not inherit the author's reasoning. A linter or CI test suite is the other alternative, and it is cheaper and deterministic, but it only checks what you already thought to assert. Swarm's reviewers are trying to catch what you did not assert, which is exactly the part that cannot be made deterministic.
Maintenance, versioning and licence
The project is MIT licensed, which permits commercial use, modification and redistribution provided the licence and copyright notice are retained. That is a permissive baseline and it is the same licence most OpenCode ecosystem tooling uses, so it removes a procurement objection rather than creating one. Nothing here is legal advice, and if you vendor or redistribute the plugin you should read the LICENSE file yourself. On maintenance, the versioning is the notable signal. The three most recent releases are v7.175.0, v7.174.0 and v7.173.1, all within roughly a day of each other, and the last push is the same day as the newest release. A patch number in the 170s on a major version of 7 means a very high release cadence. That cuts both ways. Fixes land fast, and the surface you pinned can move under you between installs. The README's own note that the agent roster is generated from current plugin configuration, and that the README list is not the source of truth, is the practical consequence: pin a version if you need reproducibility, and read /swarm agents after every upgrade rather than trusting a list you read once. The documentation set is docs/getting-started.md, docs/configuration.md, docs/architecture.md, docs/skill-optimizer.md and docs/adding-a-language.md, which is a reasonable spread for a project at this stage.
Editorial conclusion
Adopt Swarm if you already run OpenCode and want review, test and security passes to be separate agents from the one that wrote the code, and you accept that every one of those passes costs tokens. Skip it if you want a drop-in tool that works regardless of which agent is active, or if you cannot tolerate a pipeline that silently does nothing when the wrong agent is selected. Before you rely on it, run /swarm agents and confirm the roster matches what you expect, check that ~/.config/opencode/opencode-swarm.json exists after install, and verify that the native explore and general agents were disabled in opencode.json, because the installer changes that file for you.
Community notes