ZaxbyHub/opencode-swarm

OpenCode Swarm – AI‑driven, gated code‑generation pipeline

What it is – A plugin for the OpenCode AI‑coding platform that turns a single AI session into a miniature development team. The plugin automatically creates a roster of specialised agents (architect, coder, reviewer, test‑engineer, security‑critic, docs, etc.) and runs the code‑generation workflow through a gated pipeline so that nothing is merged until every required check passes.

Why it matters – Most AI‑coding tools let one model write code and then ask the same model if the code is good. Swarm separates concerns: planning, implementation, review, testing, security scanning and documentation are each handled by a dedicated, read‑only model instance. This reduces the “model said it’s done → it actually works” trust gap and gives you production‑grade guardrails without manual hand‑offs.

Core concepts

Concept	What the README says
Agents	A live roster (/swarm agents) is generated from the plugin config. Core agents include architect, coder, reviewer, test_engineer, critic, critic_oversight, sme, docs, plus many optional/conditional agents (designer, various critics, curators, councils).
Gated pipeline	Code never ships without reviewer + test‑engineer approval. Additional gates (critic, drift verifier, hallucination verifier, etc.) can be enabled per phase.
DEEP_DIVE Protocol	On‑demand, read‑only audit of the whole codebase using specialised agents.
External skill curation	Optional pipeline that discovers, quarantines and validates external “skill” plugins via regex‑based injection/unsafe‑instruction scans and provenance checks before they can be promoted.
Skill optimizer	Manual, single‑skill optimizer (/swarm skill‑opt …) that drafts, smoke‑tests, validates and atomically activates a SKILL.md candidate.
Phase completion gates	Each phase must pass completion‑verify and drift‑verifier gates before the architect moves on.
Resumable sessions	All state is stored under .swarm/; a session can be paused and resumed later.
PR monitor	Optional GitHub PR subscription that polls CI status via the gh CLI and feeds results into the AutomationEventBus.
Language support	13 first‑class language profiles (TS/JS, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP) with tree‑sitter parsing for 20 grammars.
Security guardrails	Built‑in SAST, secrets scanning, dependency audit, static shell‑write detection (POSIX, PowerShell, cmd), scope enforcement, and destructive‑command blocking.
Execution modes	Session‑level modes (Balanced, Turbo, Lean Turbo, Full‑Auto) trade safety vs speed; a project‑level execution_mode (strict, balanced, fast) sets default hooks.

---

Installation & first‑run

# Recommended single‑command install (requires Bun ≥1.3.13 or Node ≥22.13)
bunx opencode-swarm install

The installer registers the plugin with OpenCode, disables the native explore and general agents, writes a global config at ~/.config/opencode/opencode-swarm.json, and creates a project‑override stub if none exists.

If you prefer npm:

npm install -g opencode-swarm && opencode-swarm install

After installation, launch OpenCode and pick the Swarm architect from the agent picker (or use the default if it was auto‑selected). The first run creates the .swarm/ directory and populates the configuration.

Typical workflow (as shown in the README demo)

1. Prompt – e.g. Build me a JWT auth helper with tests.
2. Architect creates a phased implementation plan and sends it through a critic gate.
3. Coder writes the code for the current task.
4. Automated checks (SAST, secrets, dependency audit) run.
5. Reviewer validates correctness and security.
6. Test engineer writes and executes tests.
7. Architect runs a regression sweep; if any gate fails, the loop returns structured feedback to the responsible agent.
8. Docs and retrospectives are updated automatically.
9. All artefacts (plan, evidence, telemetry) are stored in .swarm/ for later inspection (/swarm evidence, /swarm status).

---

Key commands (slash‑style, used inside an OpenCode session)

Command	Purpose
/swarm help	List all Swarm commands.
/swarm agents	Show the live roster of registered agents.
/swarm status	Current phase / task information.
/swarm show‑plan	Display the full implementation plan (optionally filtered by phase).
/swarm evidence	Show test, review and security results for a task.
/swarm pr subscribe …	Subscribe to a GitHub PR for CI feedback.
`/swarm auto‑proceed [on	off]`
`/swarm turbo [on	off], /swarm full‑auto [on
/swarm reset --confirm	Clear all Swarm state.
/swarm diagnose	Health check and version information.

---

Configuration

• Global config lives at ~/.config/opencode/opencode-swarm.json.
• Project‑level overrides can be placed in .opencode/opencode-swarm.json (opt‑in).
• Important toggles include:
  • external_skills.curation_enabled – enable the external skill discovery pipeline.
  • skill_opt.enabled – turn on the single‑skill optimizer.
  • pr_monitor.enabled – activate GitHub PR monitoring.
  • execution_mode – set default safety profile (strict, balanced, fast).

---

Updating

Because OpenCode caches plugins, a normal restart does not pull a newer npm version. Use the provided helpers:

bunx opencode-swarm update   # refresh cache only
# or
bunx opencode-swarm install  # full reinstall (re‑asserts config)

/swarm diagnose reports the running and latest npm versions; set version_check: false to silence the background check.

Who might use it?

• Developers who rely on AI code generation but need production‑grade safety (security review, test coverage, audit trails).
• Teams that want a “single‑prompt” experience while still enforcing code‑review and testing policies.
• Organizations that need traceable, resumable AI‑driven development sessions across multiple languages.

---

Bottom line

OpenCode Swarm is a real, installable plugin that augments the OpenCode AI coding environment with a full‑stack, multi‑agent workflow. By turning a lone model into a coordinated team and enforcing gated execution, it aims to make AI‑generated code trustworthy enough for production use while remaining configurable and language‑agnostic.