# opencode-swarm's strongest gates are the ones you have to switch on

> ZaxbyHub/opencode-swarm is a TypeScript plugin for OpenCode that turns one coding session into an architect-led roster of agents with reviewer and test-engineer approval before anything ships. The pipeline shape is the interesting part, and so is what ships disabled: the completion gate, phase review, external skill curation, skill optimizer, and PR monitor all need a config key or a slash command first.

**ZaxbyHub/opencode-swarm** —   Architect-centric agentic swarm plugin for OpenCode. Hub-and-spoke orchestration with SME consultation, code generation, and QA review.

- Repository: https://github.com/ZaxbyHub/opencode-swarm
- Stars: 489 · Forks: 54
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/zaxbyhub-opencode-swarm

## One install command, and a mode picker that decides whether the gates run

The whole installation is one line, and it does more than fetch a package.

```bash
bunx opencode-swarm install
```

That single command installs the package, registers it as an OpenCode plugin, disables conflicting default agents, and creates a ready-to-edit config at `~/.config/opencode/opencode-swarm.json`. Runtime requirements are stated in the same breath: Bun 1.3.13 or newer, checked with `bun --version`, or Node.js 22.13 or newer for npm installs, because the Node-hosted sidecar uses the built-in `node:sqlite`. The npm path exists and is spelled out rather than left implicit.

```bash
npm install -g opencode-swarm && opencode-swarm install
```

The first-run note is the part that decides whether any of this matters. The installer also writes the global plugin config, creates a project override when one is missing, and disables the native `explore` and `general` agents in `opencode.json`. And then: if you are not using a Swarm architect, the Swarm gates, reviewers, and test agents are bypassed. You have to open the OpenCode agent or mode picker and choose the Swarm architect when you want it. So the installer can leave a project looking gated while every gate is inert, and nothing about the install output tells you which state you are in.

## The roster the README enumerates is declared untrustworthy in the same sentence

The README names 19 agents in a run-on list: 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. It then tells you to run a command for the live roster, and says in as many words that the command is the source of truth and that this list is not.

```bash
/swarm agents
```

The roster is generated from the current plugin configuration, which is the right call for something whose roster can change with a config key or a release. It also means the prose list ages badly by construction, and there is no version stamp on it.

What the names do carry is structure. The critic family is six entries deep and each one names a different failure mode: a finding validator, an oversight pass, a sounding board, a drift verifier, and a hallucination verifier sitting alongside the base critic. The council is a deliberate trio, a generalist, a skeptic, and a domain expert. The curators are a two-step pair, an init and a phase. Nobody reading that list needs the prose to understand that this project treats a single reviewer as insufficient, and the naming is doing the arguing.

## Phase review is advisory by default and v8 changes that with a cost number

The headline gate is simple to state: code never ships without reviewer plus test engineer approval. Around it sit two more layers. Phase completion gates apply a completion-verify gate and a drift verifier gate before a phase is allowed to close. And an independent auto-review engine runs a bounded whole-diff review in a fresh read-only model session, producing structured diff-anchored findings with optional independent validation behind them.

The qualifier is in the same bullet. Phase review is advisory by default, and the completion gate is evidence-backed and opt-in. The reason given is cost: v7 stays opt-in, and v8's default is pinned to a committed 30-diff cost burn-in. A burn-in is a measurement someone committed to a release note, not a benchmark anyone can rerun from the docs, so treat 30 diffs as the project's own accounting of what the gate costs rather than as a published figure.

This is the honest shape of the design. An agent that writes code and an agent that reviews it are different sessions, the reviewer is read-only, and the findings are anchored to diff positions so a human can check them. What you get by default is a recommendation. What you get after turning the gate on is a block, and whether you want the block depends on how much you trust a reviewer that shares a model family with the writer.

## Two pipelines for outside skills, both switched off by default

Third-party skill handling is split across two features, and both are inert until a config key in opencode-swarm.json is set.

The external skill curation pipeline covers discovery, quarantine, evaluation, and promotion of candidates from configured sources, 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 validation gates before evaluation: a prompt injection scan of 12 regex patterns, an unsafe instruction scan of 25 patterns, and a provenance integrity check covering SHA-256, timestamp, URL, publisher, and hash verification. That is a sensible funnel for code that will end up in a model's context.

The skill optimizer is the narrower one, it is manually activated, and it ships disabled behind `skill_opt.enabled: false`. Curation is off by default too, turned on with `external_skills.curation_enabled: true`. The optimizer drives one allowlisted `SKILL.md` candidate at a time through a fixed sequence: deterministic draft, smoke, validation against an evaluation substrate, manual approval, then atomic activation or rollback. The command surface is the rollback story.

```bash
/swarm skill-opt plan|run|status|diff|approve|reject|rollback|history
```

The project describes it as bounded, restartable, and reversible, and unable to mutate source, harness, or security surfaces. Manual approval sitting in the middle of the chain is what makes the atomic activation claim worth anything: nothing is swapped in without a human at that step.

## GitLab support that reports unavailable instead of inventing a status

GitLab is supported as a first-class forge, and the interesting part is the shape of the support rather than the feature list. Merge request and issue URLs of the form `https://<gitlab-host>/owner/repo/-/merge_requests/N` and `/-/issues/N` are accepted by `/swarm pr-review`, `/swarm pr-feedback`, `/swarm pr subscribe/unsubscribe`, `ci-monitor`, publication recording, and issue ingestion. Self-hosted hosts are derived from the remote or from a `forge` block of `{ provider, base_url }`, default `auto`, and an ambiguous remote fails closed rather than guessing.

The URL security controls are stated as identical to the GitHub path: HTTPS only, rejection of private and localhost targets, IDN protection, and credential stripping. The `glab` binary resolves through the same hardened resolver contract as `gh`, with `OPENCODE_SWARM_GLAB_BINARY` as the override.

Then there is the admission. GitLab does not synthesize GitHub's `statusCheckRollup`, `reviewDecision`, or `mergeStateStatus`, and instead of returning a plausible value the plugin surfaces an explicit unavailable result. That is the correct call for tooling whose output gates a merge. The same paragraph admits that glab-backed live merge request polling is not built yet and is tracked as follow-up issue 2882, which means the background PR monitor, which polls through `gh`, is a GitHub-only feature in practice even though the slash commands are not.

```bash
/swarm pr subscribe <pr-url|owner/repo#N|N>
```

The monitor itself is opt-in through `pr_monitor.enabled: true`. With `auto_pr_feedback: true`, CI failures and merge conflicts activate PR_FEEDBACK mechanically only when no other workflow owns the session, and are otherwise queued for a later round.

## Scope enforcement, and the bullet that stops mid-word

The security story has three per-task pieces and one structural piece. The per-task pieces are SAST, secrets scanning, and a dependency audit. The structural piece is scope enforcement, which validates write targets against a declared scope with cross-process persistence, TTL expiry, and scope-aware destructive command blocking.

The detail that matters is in how paths arrive. Scope enforcement handles both a single string and an array-shaped argument, with `files[]`, `paths[]`, and `targetFiles[]` named explicitly. That is a small sentence with a large implication: a checker that validates one path will pass a run where the same intent arrived as a list, and a list is exactly what a multi-file edit looks like.

The bullet then stops. It ends mid-word, at to prevent s, so whatever the array handling is meant to prevent is not finished in the published text. The last line of the list ends there, with no later bullet picking the sentence back up.

The rest of the tree does not fill the gap either. What can be confirmed from outside is the shape of the claim: three per-task scanners, a scope validator with an explicit array-argument fix, and an unfinished sentence describing the failure that fix prevents.

## Thirteen language profiles, twenty grammars, two test directories

Language support is counted two ways, and the counts do not match, which is the interesting part. There are 13 full language profiles: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, and PHP. Tree-sitter parse validation runs across 20 grammars, which the project explains as adding CSS, Bash, PowerShell, INI, and Regex, plus `.tsx` and `.c` aliases. Thirteen plus five is eighteen, and the two aliases close the gap to twenty, so the numbers are consistent once you count the aliases as grammars rather than as languages.

The repository layout is where the other numbers come from. Both `test/` and `tests/` exist at the top level, which is an invitation to guess which one the gates run. There is a `.agents/`, a `.claude/`, and a `.opencode/` directory, alongside an `AGENTS.md` and a `CLAUDE.md`, so instructions for at least three agent harnesses live in the tree at once. A single file, `swarm-busy-test3.db`, sits at the root next to `package.json` and `tsconfig.json`, and a database file with a test-shaped name at the top of a project is worth understanding before it gets mistaken for state.

The rest is conventional and says something about the build. `biome.json` and `.biomeignore` for lint and format, `bun.lock` and `bunfig.toml` for Bun, `release-please-config.json` with `.release-please-manifest.json` for versioned releases, an `opencode-swarm.schema.json` at the root for the config it asks you to edit, plus `binaries/`, `runners/`, `scripts/`, `references/`, `evaluation-fixtures/`, and a single example directory, `examples/syntax-check/`.

## The published package carries dist, grammars, binaries, and no source

package.json is where the project's real shape shows. It is `type: module`, MIT licensed, published publicly to the npm registry, with `main` at `dist/index.js`, types at `dist/index.d.ts`, and a single binary named `opencode-swarm` pointing at `./dist/cli/index.js`. Engine floors match the README: Bun 1.3.13 and Node 22.13.

The files array is the part worth reading twice. It starts with `dist`, then lists `dist/lang/grammars` as a separate entry, which adds nothing because everything under `dist` is already included. Then `binaries`, then `evaluation-fixtures`, then twenty-four named `.opencode/skills/` directories before the listing is cut off mid-name, at `.opencode/skills/l`. The skills are the real payload: brainstorm, specify, clarify-spec, clarify, discover, consult, council, deep-dive, deep-research, swarm-implement, swarm-plan, swarm-pr-review, swarm-pr-feedback, swarm-pr-subscribe, swarm-ci-monitor, issue-ingest, critic-gate, execute, phase-wrap, and others. None of `src/` is published.

Two smaller things. The version is 7.188.5, so the minor slot is being used as a counter rather than as a compatibility promise, and three releases landed across 2026-10-01 and 2026-10-02. And the README's badge link points at a different owner spelling than the package metadata and the issue tracker do, which is the kind of thing to resolve before you file anything upstream.

## Conclusion

The plugin fits a team already working inside OpenCode that wants a written review trail on every change and is disciplined enough to pick the Swarm architect each session. It does not fit anyone expecting the gates to be on out of the box, because the completion gate, the external skill pipeline, the skill optimizer, and the PR monitor all ship switched off, and choosing a different architect bypasses the reviewers entirely. Before installing, read the npm files list rather than the feature list: the package ships dist, grammars, binaries, evaluation fixtures, and 24 skill directories, with no TypeScript source, so a review policy that expects to read the code finds nothing to read. The last push was on 2026-10-01 and three releases landed on 2026-10-01 and 2026-10-02, so pin the version you audit.

## FAQ

### What does opencode-swarm install, and what does it change in my OpenCode setup?

One command, `bunx opencode-swarm install`, 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`. It also writes the global plugin config, creates a project override when one is missing, and disables the native `explore` and `general` agents in `opencode.json`.

### Do the opencode-swarm review gates run as soon as I install it?

Not necessarily. The README states that if you are not using a Swarm architect, the Swarm gates, reviewers, and test agents are bypassed, so you have to open the OpenCode agent or mode picker and choose the Swarm architect. The phase review itself is also advisory by default and the completion gate is opt-in in v7.

### What runtimes does opencode-swarm need, and is npm supported?

Bun 1.3.13 or newer, checked with `bun --version`, or Node.js 22.13 or newer for npm installs, since the Node-hosted sidecar uses the built-in `node:sqlite`. The npm route is `npm install -g opencode-swarm && opencode-swarm install`, and package.json declares both engine floors.

### How much of opencode-swarm's source can I read after installing it from npm?

The package files list includes dist, dist/lang/grammars, binaries, evaluation-fixtures, and twenty-four .opencode/skills directories before the listing is cut off, but not src. You get the compiled entry point, the tree-sitter grammars, and the skills that make up the actual behaviour, so reading the implementation means reading the bundle or the repository.

## Sources

- [Issues](https://github.com/ZaxbyHub/opencode-swarm/issues)
- [License: MIT](https://github.com/ZaxbyHub/opencode-swarm/blob/main/LICENSE)
- [README](https://github.com/ZaxbyHub/opencode-swarm/blob/main/README.md)
- [Releases](https://github.com/ZaxbyHub/opencode-swarm/releases)
- [ZaxbyHub/opencode-swarm on GitHub](https://github.com/ZaxbyHub/opencode-swarm)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zaxbyhub-opencode-swarm