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

``bash
npm install -g swarm-control
`

Setup

After installation, run the setup command:

`bash
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:

`bash
swarm-control set-agent
`

For example:
`bash
swarm-control set-agent anthropic/claude-3-5-sonnet-20241022
`

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

Usage

$3

`
/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
`

$3

`
/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

$3

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

$3

`
/swarm_spawn # Start a swarm task
/swarm_status # Check swarm status
`

Configuration

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

`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

$3

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

$3

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

$3

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

$3

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

$3

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

Examples

$3


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

$3

`
/swarm_spawn "Add error handling to all API endpoints"
`

$3

`
/swarm_spawn "Add unit tests to all service files"
`

$3

`
/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

`bash
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