Swarm Control

OpenCode plugin for multi-agent swarm coordination. Decompose complex programming tasks and execute them in parallel across multiple AI subagents.

Features

• Task Decomposition: Automatically breaks down complex tasks into file-based subtasks
• Parallel Execution: Spawns up to 4 worker subagents to work in parallel
• Dependency Management: Respects dependencies between subtasks
• File Locking: Prevents conflicts when multiple workers access the same files
• State Persistence: Tracks task progress and worker status
• Partial Completion: Continues execution even if some subtasks fail

Installation

npm install -g swarm-control

Setup

After installation, run the setup command:

swarm-control setup

This will:

1. Install the swarm-control package to OpenCode's node_modules
2. Add it to the plugin list in your OpenCode config

Important: You must restart OpenCode after running setup for the plugin to be loaded.

Configuration

Before using the swarm, you must configure the model used for task decomposition:

swarm-control set-agent <model-name>

For example:

swarm-control set-agent anthropic/claude-3-5-sonnet-20241022

The model is stored in your OpenCode config file (~/.config/opencode/opencode.json).

Usage

Starting a Swarm Task

/swarm_spawn "your task description"

Example:

/swarm_spawn "Add error handling to all API endpoints in src/api/"

Options:

• maxWorkers (optional): Maximum number of workers (default: 4, max: 4)

Example with options:

/swarm_spawn "Refactor authentication module" --maxWorkers 2

Checking Swarm Status

/swarm_status

This shows:

• Current task information
• Subtask progress
• Worker status
• Any errors or failures

How It Works

1. Task Analysis: The LLM analyzes your task and identifies relevant files
2. Decomposition: The task is broken down into 1-4 file-based subtasks
3. Worker Spawning: Child sessions (subagents) are created as workers
4. Parallel Execution: Independent subtasks run in parallel
5. Dependency Resolution: Subtasks with dependencies wait for completion
6. File Locking: Workers wait for files to be unlocked before accessing them
7. Result Aggregation: Results from all workers are combined into a summary

File Locking

When multiple workers need to access the same file:

• First worker acquires the lock
• Subsequent workers wait in a queue
• Lock is released when the worker finishes
• Next worker in the queue acquires the lock

This prevents conflicts and ensures file integrity.

Error Handling

• If a subtask fails, the swarm continues with other subtasks
• Failed subtasks are marked with ❌ and show error details
• File locks are automatically released on error
• The final summary shows both completed and failed subtasks

Commands

CLI Commands

swarm-control setup      # Install the plugin
swarm-control set-agent <model>  # Set model for decomposition
swarm-control uninstall  # Remove the plugin
swarm-control reset      # Reset swarm state (keeps configuration)

OpenCode Tools

/swarm_spawn <task>      # Start a swarm task
/swarm_status            # Check swarm status

Configuration

The swarm model is stored in ~/.config/opencode/opencode.json:

{
  "swarm": {
    "model": "anthropic/claude-3-5-sonnet-20241022"
  }
}

State Management

Swarm state is persisted to ~/.config/swarm-control/state.json:

• Current task information
• Subtask status
• Worker information
• File locks

Use swarm-control reset to clear state without removing configuration.

Requirements

• OpenCode >= 1.1.7
• Node.js >= 18.0.0

Troubleshooting

Plugin not loaded after installation

Make sure to restart OpenCode after running swarm-control setup.

"Swarm model not configured" error

Run swarm-control set-agent <model-name> to configure the model before using /swarm_spawn.

"A swarm task is already in progress" error

Wait for the current task to complete or use swarm-control reset to clear state.

Workers not creating sessions

Check that OpenCode has permission to create child sessions and that your API quota is sufficient.

Decomposition fails

Try using a more capable model (e.g., Claude Sonnet instead of Haiku) for better decomposition quality.

Examples

Simple Single-File Task

/swarm_spawn "Add JSDoc comments to src/utils.ts"

Multi-File Task

/swarm_spawn "Add error handling to all API endpoints"

Parallelizable Task

/swarm_spawn "Add unit tests to all service files"

Task with Dependencies

/swarm_spawn "Refactor authentication and update all consuming code"

Limitations

• Maximum 4 workers (configurable via command, but limited to 4)
• File-based decomposition (may not work for complex architectural changes)
• No task history (status only shows current task)
• No automatic retry for failed subtasks

Uninstallation

swarm-control uninstall

This removes:

• swarm-control from OpenCode's plugin list
• Swarm configuration from OpenCode config

To also remove state, run swarm-control reset before uninstalling.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

ISC

Support

For issues or questions:

• Check the troubleshooting section above
• Open an issue on GitHub
• Join the OpenCode Discord community