Configuration and Customization
Relevant source files
The following files were used as context for generating this wiki page:
Configuration and customization in OpenCode Swarm provide the foundational framework for orchestrating multi-agent workflows, defining safety boundaries, and tailoring agent behaviors to specific project needs. The system centers on a structured configuration schema that governs everything from agent model selection to the enforcement of mandatory Quality Assurance (QA) gates and context budget management.
The architecture ensures that the plugin remains portable across different environments while maintaining strict state containment within the project's .swarm/ directory. By leveraging dynamic tool mapping and skill propagation, developers can customize the swarm's capabilities and ensure consistent application of project-specific standards across all subagents.
Sources: src/agents/architect.ts:35-55, AGENTS.md:15-30
Configuration Architecture
The configuration system is built around a centralized schema and a runtime hook that enhances system prompts based on the current project state. The architect agent serves as the central orchestrator, using configuration data to determine which tools are available and how tasks should be delegated.
Core Components
The following diagram illustrates the relationship between configuration, the orchestrator, and the resulting agent behavior:
This diagram shows how plugin configuration flows through the system to influence both the orchestrator and the execution environment of subagents.
Sources: src/hooks/system-enhancer.ts:500-550, src/agents/architect.ts:1000-1050
QA Gate Configuration
One of the most critical aspects of customization is the definition of QA gates. The system supports a tiered approach to verification, where the complexity of the change determines the intensity of the review.
Mandatory QA Gates
The configuration allows for enabling or disabling specific gates, though some are reinforced by runtime hooks that block execution if bypassed.
| Gate Name | Default | Description |
|---|---|---|
reviewer | ON | Code review of implementation output. |
test_engineer | ON | Test generation and verification. |
sme_enabled | ON | Subject Matter Expert consultation. |
sast_enabled | ON | Static security scanning. |
council_mode | OFF | Multi-member holistic review for high-impact changes. |
drift_check | ON | Verifies implementation against spec intent. |
Sources: src/agents/architect.ts:1140-1170, src/agents/architect.ts:310-335
Change Classification Tiers
Configuration governs how tasks are classified to determine the required QA pipeline:
- Tier 1 (Documentation): Requires standard reviewer only.
- Tier 2 (Standard Code): Requires reviewer and test engineer.
- Tier 3 (Critical): Requires dual reviews and adversarial testing (e.g., security paths).
Sources: src/agents/architect.ts:340-365
Agent and Tool Customization
The swarm's capabilities are customized through AGENT_TOOL_MAP and role-specific identity prompts. The Architect's prompt is dynamically constructed by substituting placeholders with configuration values.
Tool Mapping
Tools are associated with agents based on their role definitions. Some tools are "opt-in" and only appear if the corresponding feature is enabled in the configuration (e.g., memory tools or council tools).
The relationship between an agent's definition and its runtime configuration.
Sources: src/config/constants.ts, src/agents/architect.ts:20-30
Identity and Prefixes
In multi-swarm environments, agents are customized using an AGENT_PREFIX (e.g., mega_architect). Configuration ensures that at least one prefixed agent is marked as primary in the registry.
Sources: AGENTS.md:120-135, src/agents/architect.ts:55-65
Context and Budget Management
Customization includes managing the "Context Budget," which prevents LLM context window overflows by ranking and prioritizing information injected into system prompts.
Scoring and Prioritization
When scoring is enabled, information is ranked according to weights defined in the configuration (defaulting to Category: 40%, Confidence: 35%, Keywords: 25%).
| Priority | Category | Status |
|---|---|---|
| 1 (Highest) | Task Specs / Plan Cursor | Always Preserved |
| 2 | Gate Verdicts / Active Status | Always Preserved |
| 3 | Decisions / Agent Context | Compressed |
| 4 (Lowest) | Old SME Cache / Resolved Blockers | Discarded |
Sources: src/hooks/system-enhancer.ts:550-600, src/agents/architect.ts:75-95
State and Safety Boundaries
Configuration enforces strict safety boundaries to ensure plugin stability across different platforms.
Runtime Invariants
The system follows "non-negotiable invariants" that govern customization:
- Containerization: All runtime state must live under
.swarm/. - Fast Init: Plugin registration must be bounded and fail-open.
- Subprocesses: Must be non-interactive, killable, and use array-form spawning.
- No Self-Verification: Implementation agents (Coder) are prohibited from running verification commands like
npm test, ensuring separation of concerns.
Sources: AGENTS.md:35-85, src/hooks/system-enhancer.ts:760-775
Spec-Writing Discipline
Customization of destructive operations follows a strict discipline:
- Error Strategy: Choose between
FAIL_FASTorBEST_EFFORT. - Platform Compatibility: Explicitly handle API differences between Windows, macOS, and Linux (e.g., atomic directory overwrites).
Sources: src/agents/architect.ts:255-265
Summary
Configuration and Customization in OpenCode Swarm provide a robust mechanism for controlling agent behavior while ensuring architectural integrity. By combining a flexible schema with mandatory safety gates and dynamic context prioritization, the system allows for sophisticated multi-agent orchestration tailored to the specific constraints and requirements of any software project. Significant emphasis is placed on "Separation of Concerns," where configuration dictates that only implementation agents modify source code, while specialized gate agents handle verification.