Getting Started and Setup
Relevant source files
The following files were used as context for generating this wiki page:
Getting started with OpenCode Swarm involves setting up a multi-agent orchestration environment designed to handle complex software development tasks. The system is built on a "prime directive" of maintaining a runtime contract that is loadable, portable, and safe across multiple operating systems (Windows, macOS, Linux) and host contexts (GUI, TUI, Bun, Node).
Sources: AGENTS.md:15-18, src/agents/architect.ts:50-52
The setup process covers environment preparation, local development workflow, and adherence to non-negotiable engineering invariants. These invariants ensure that the swarm plugin remains performant and does not corrupt state across different sessions or platforms.
Sources: AGENTS.md:20-25, contributing.md:15-20
Local Development Setup
To begin contributing or developing with the project, you must set up the Bun runtime environment and configure your local branch. The project uses bun as its primary package manager and test runner.
Initial Environment Preparation
- Branch Setup: Always start from the latest
mainbranch. - Installation: Use
bun install --frozen-lockfileto ensure dependency consistency.
git checkout main && git pull origin main
git checkout -b <type>/<short-description>
bun install --frozen-lockfile
Sources: contributing.md:27-31
Quality and Validation Tiers
Before changes are pushed, a tiered local check must be performed to ensure code quality and adherence to project standards.
| Tier | Purpose | Commands |
|---|---|---|
| Tier 1 | Quality & Linting | bun run typecheck, bunx biome ci . |
| Tier 2 | Unit Tests | bun test tests/unit/... |
| Tier 3 | Integration | bun test tests/integration |
| Tier 4 | Security | bun test tests/security, bun test tests/adversarial |
| Tier 5 | Smoke Tests | bun run build, bun test tests/smoke |
Sources: contributing.md:46-75
Core Engineering Invariants
The project is governed by 12 non-negotiable invariants defined in the engineering contract. These are critical for anyone setting up or modifying the system architecture.
1. Plugin Initialization
Initialization must be fast and bounded. No unbounded filesystem scans or network calls are permitted during the startup path. Any init-path work must be wrapped in timeouts to ensure the OpenCode plugin host does not silently drop the plugin.
Sources: AGENTS.md:32-41
2. Runtime Portability
The main plugin bundle (dist/index.js) must remain Node-ESM-loadable. Direct Bun.* calls are prohibited outside of specific compatibility utilities to ensure it can run in Node-hosted plugin contexts.
Sources: AGENTS.md:43-50
3. Containment and State
All runtime state must be contained within the project root .swarm/ directory. Tools must not create directories in arbitrary locations or pollute the Git history with runtime artifacts.
Sources: AGENTS.md:65-75
Orchestration Architecture
The system utilizes an Architect agent as the central orchestrator, managing subagents through a structured delegation protocol.
Operational Modes
The Architect transitions through several operational modes based on the current state of the project plan.
The operational mode is derived from the plan state: DISCOVER if no plan exists, EXECUTE if tasks are in progress, and PHASE-WRAP if all tasks are complete.
Sources: src/hooks/system-enhancer.ts:1330-1370, src/agents/architect.ts:600-650
Subagent Delegation
The Architect "thinks" while subagents "do". Communication is handled via the Task tool.
| Agent | Responsibility |
|---|---|
explorer | Codebase analysis and factual mapping. |
coder | Direct implementation of code changes. |
reviewer | Quality gate for correctness and security. |
test_engineer | Test generation and execution. |
docs | README, API docs, and guide synthesizer. |
Sources: src/agents/architect.ts:400-420, src/agents/explorer.ts:25-35, src/agents/docs.ts:50-60
Setup for Automated Documentation
The system includes a Documentation Discovery Mode that activates during the initial codebase "reality check."
Discovery Workflow
- Manifest Building: Scans root (README, CONTRIBUTING, CHANGELOG) and
docs/**/*.md. - Extraction: Reads the first 30 lines of each file to extract titles and summaries.
- Caching: Writes pointers to
.swarm/doc-manifest.json.
Conclusion
Setting up OpenCode Swarm requires strict adherence to engineering invariants to maintain cross-platform stability. By following the tiered validation process and utilizing the Architect's structured delegation modes, developers can ensure that the swarm remains portable, recoverable, and performant. Adhering to the .swarm/ containment and plan durability rules is essential for preventing state corruption across orchestration sessions.
Sources: AGENTS.md:27-30, src/agents/architect.ts:220-230