Introduction to OpenCode Swarm

Relevant source files

The following files were used as context for generating this wiki page:

• src/agents/architect.ts
• src/agents/coder.ts
• src/agents/critic.ts
• src/agents/explorer.ts
• src/index.ts
• AGENTS.md
• contributing.md
• CLAUDE.md

OpenCode Swarm is an architect-centric multi-agent system designed for automated code generation, analysis, and implementation. It operates on a hub-and-spoke model where a central Architect agent digests complex requirements into atomic tasks and orchestrates specialized subagents to perform implementation, review, and documentation.
Sources: src/index.ts:168-175, src/agents/architect.ts:91-100

The system is governed by a "root engineering contract" that ensures it remains portable, bounded, and safe across various runtime environments, including Windows, macOS, and Linux. It focuses on maintaining code quality through a mandatory, tiered QA lifecycle that combines automated tool gates with human-like agent verification passes.
Sources: AGENTS.md:16-19, CLAUDE.md:15-18

Hub-and-Spoke Architecture

The architecture centers around the Architect agent, which acts as the primary reasoning engine. Subagents are specialized "doers" with smaller context windows and targeted skills.

The Architect maintains the "source of truth" in .swarm/plan.md and .swarm/context.md, ensuring that subagents only receive the specific context necessary for their assigned tasks.
Sources: src/index.ts:168-175, src/agents/architect.ts:91-96

Core Agent Roles

The swarm utilizes a variety of specialized roles to ensure comprehensive project handling:

Agent	Responsibility	Key Characteristics
Architect	Orchestration, planning, and task decomposition.	Does NOT write code; delegates to Coder.
Explorer	Codebase discovery and factual mapping.	Read-only; scans structure and patterns.
Coder	Direct implementation of code changes.	Uses Edit/Write/Patch tools; strictly follows task specs.
Reviewer	Code review for correctness and security.	Returns verdicts (APPROVED/REJECTED).
TE	Test generation and execution.	Validates behavior through PASS/FAIL test runs.
SME	Domain-specific technical guidance.	Provides research findings and confidence ratings.
Critic	Quality gate for the Architect's reasoning.	Reviews plans and provides pushback as a "Sounding Board."

Sources: src/agents/architect.ts:114-125, src/agents/explorer.ts:4-15, src/agents/coder.ts:4-15, src/agents/sme.ts:4-15, src/agents/critic.ts:108-115

Operational Workflow

The swarm operates through distinct "modes" based on the state of the project and user requests.

Operational Modes

• MODE: DISCOVER: Runs broad scans to identify language, frameworks, and entry points. Sources: src/agents/architect.ts:709-715
• MODE: PLAN: Utilizes the save_plan tool to generate a structured .swarm/plan.md. Sources: src/agents/architect.ts:784-793
• MODE: EXECUTE: The implementation phase where the Architect delegates atomic tasks to the Coder agent. Sources: src/agents/architect.ts:813-825
• MODE: CRITIC-GATE: A mandatory pause before implementation where the Critic agent must approve the plan. Sources: src/agents/architect.ts:805-811

The QA Gate Lifecycle

Implementation tasks follow a strict two-stage verification process to prevent regressions and security vulnerabilities.

Stage A: Automated Tool Gates

Before agent review, code must pass automated checks:

1. diff: Analysis of changes.
2. syntax_check: Ensures code parses correctly.
3. placeholder_scan: Checks for TODOs or stubs.
4. lint: Verifies coding standards.
5. build_check: Ensures the project still compiles.

Stage B: Agent Review Gates

Once automated gates pass, the Architect dispatches:

• Reviewer: Conducts a logic and security review.
• Test Engineer: Generates and executes functional tests.
  Sources: src/agents/architect.ts:182-260

Engineering Invariants

The project is governed by non-negotiable invariants to ensure stability:

1. Plugin Initialization: Must be fast, bounded, and fail-open. Sources: AGENTS.md:32-43
2. Runtime Portability: The core plugin must remain Node-ESM-loadable without direct Bun.* calls. Sources: AGENTS.md:45-52
3. Subprocesses: Must use array-form spawn, explicit cwd, and best-effort proc.kill() in finally blocks. Sources: AGENTS.md:54-66
4. Containment: Runtime state must reside only under the .swarm/ directory. Sources: AGENTS.md:68-80
5. Plan Durability: The .swarm/plan-ledger.jsonl is the authoritative source of truth for project state. Sources: AGENTS.md:82-89

Implementation Details: Code Injection

The system enhances the model's system prompt dynamically based on the current phase and active agent.

// Example from src/hooks/system-enhancer.ts
export function buildSpecDriftAdvisory(args: {
	reason: string;
	currentHash: string | null;
	storedHash: string;
}): string {
	return [
		'[spec-drift]',
		`Reason: ${args.reason}`,
		`Stored spec hash: ${args.storedHash}`,
		`Current spec hash: ${args.currentHash ?? '(spec.md missing)'}`,
	].join('\n');
}

Sources: src/hooks/system-enhancer.ts:32-45

Summary

OpenCode Swarm provides a robust framework for agentic development by enforcing strict roles and quality gates. By isolating planning (Architect) from doing (Subagents) and requiring independent verification (Critic/Reviewer), the system minimizes AI hallucinations and ensures that generated code meets project-specific engineering standards.
Sources: src/agents/architect.ts:91-100, AGENTS.md:16-19