Swarm

Claude Code Swarm Plugin

Multi-agent coordination for Claude Code. Enables parallel task decomposition, worker spawning, and agent-to-agent communication.

Installation

1. Install the swarm CLI (required)

The plugin delegates to the swarm CLI for all operations:

bun add -g opencode-swarm-plugin
# or
npm install -g opencode-swarm-plugin

Verify installation:

swarm --version

2. Install the plugin from marketplace

# Add the swarm-tools marketplace
claude /plugin add-marketplace https://github.com/joelhooks/opencode-swarm-plugin

# Install the swarm plugin
claude /plugin install swarm@swarm-tools

3. Restart Claude Code

The plugin's MCP server will start automatically.

Usage

Slash Commands

Command	Description
/swarm <task>	Decompose task into parallel subtasks and spawn workers
/hive	Query and manage tasks (cells) in the hive tracker
/inbox	Check swarm mail inbox for messages from other agents
/status	Check swarm coordination status
/handoff	End session with proper cleanup and handoff notes

Example: Running a Swarm

/swarm refactor the auth module to use JWT tokens

This will:

1. Analyze the task and decompose into parallelizable subtasks
2. Create an epic with child tasks in the hive tracker
3. Spawn worker agents for each subtask
4. Coordinate file reservations to prevent conflicts
5. Review worker output before completion

Tools

The plugin exposes 25 tools via MCP:

Hive (Task Management)

• hive_cells - Query cells with filters
• hive_create - Create a new cell
• hive_create_epic - Create epic with subtasks
• hive_close - Close a cell with reason
• hive_query - Query with advanced filters
• hive_ready - Get next unblocked cell
• hive_update - Update cell status/description

Hivemind (Memory)

• hivemind_find - Semantic search across memories
• hivemind_store - Store a memory with embedding
• hivemind_get - Retrieve memory by ID
• hivemind_stats - Memory system statistics

Swarmmail (Agent Coordination)

• swarmmail_init - Initialize agent session
• swarmmail_inbox - Check inbox for messages
• swarmmail_send - Send message to other agents
• swarmmail_reserve - Reserve files for editing
• swarmmail_release - Release file reservations

Swarm (Orchestration)

• swarm_decompose - Generate decomposition prompt
• swarm_status - Get swarm status by epic ID
• swarm_plan_prompt - Strategy-specific planning
• swarm_validate_decomposition - Validate decomposition
• swarm_spawn_subtask - Prepare subtask for spawning
• swarm_review - Generate review prompt
• swarm_review_feedback - Send review feedback
• swarm_progress - Report progress
• swarm_complete - Mark subtask complete

Claude Code 2.1.32 Integration

Claude Code has native multi-agent capabilities as of version 2.1.32. This plugin complements those capabilities rather than replacing them.

Architecture: Two Coordination Paths

                     ┌──────────────────────────────────┐
                     │        Claude Code 2.1.32        │
                     └──────────────────────────────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     │                           │
         ┌───────────▼─────────────┐   ┌─────────▼────────────────┐
         │  Native Agent Teams     │   │   Swarm Plugin Tools     │
         │  (Teammate tool)        │   │   (MCP)                  │
         ├─────────────────────────┤   ├──────────────────────────┤
         │ • Team spawning         │   │ • Hive (git-backed)      │
         │ • Task assignment       │   │ • Hivemind (memory)      │
         │ • Real-time messaging   │   │ • Swarmmail (events)     │
         │ • UI task list          │   │ • Decomposition logic    │
         │ • Planning mode         │   │ • Review workflow        │
         │ • Sub-agent config      │   │ • File reservations      │
         └─────────────────────────┘   └──────────────────────────┘
                     │                           │
                     └───────────┬───────────────┘
                                 │
                        ┌────────▼────────┐
                        │  Worker Agents  │
                        └─────────────────┘

What Native Provides vs Plugin Additions

Capability	Native (2.1.32+)	Swarm Plugin
Agent Teams	✅ Teammate tool	⚠️ Swarmmail (event-based, persistent history)
Task UI	✅ TaskCreate/TaskList	⚠️ Hive cells (git-backed, survives compaction)
Messaging	✅ Real-time DMs	⚠️ Swarmmail (persistent, file reservations)
Planning	✅ Planning mode	⚠️ Decomposition strategies (file/feature/risk)
Sub-agents	✅ Agent config	⚠️ Worker/coordinator specialization
Memory	❌	✅ Hivemind semantic memory + embeddings
Git Persistence	❌	✅ Hive syncs to .hive/ directory
File Coordination	❌	✅ Swarmmail reservations prevent conflicts
Review Workflow	❌	✅ swarm_review + feedback loop
Strategy Selection	❌	✅ Auto-selects file/feature/risk strategies

Hooks

The plugin registers lifecycle hooks:

Hook	Action
SessionStart	Initialize session context
UserPromptSubmit	Track user prompts
PreToolUse	Pre-edit validation and pre-complete checks
PostToolUse	Track tool usage for hivemind_find, skills_use, swarmmail_init, hivemind_store, swarm_complete
PreCompact	Save state before context compaction
SessionEnd	Cleanup and sync
SubagentStart	Initialize worker agent context
SubagentStop	Cleanup worker state

Skills

always-on-guidance

Rule-oriented guidance for Claude Code agents. Loaded automatically.

swarm-coordination

Multi-agent coordination patterns. Use when spawning workers or coordinating parallel tasks.

Agents

Agent	Type	Purpose
coordinator	Foreground	Orchestrates swarm decomposition and worker spawning
worker	Foreground	Executes subtasks with file reservations
background-worker	Background	Handles tasks without MCP tool access

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
├─────────────────────────────────────────────────────────┤
│  Plugin (this package)                                  │
│  ├── MCP Server (bin/mcp-server.js)                    │
│  │   └── Shells out to: swarm tool <name> --json       │
│  ├── Commands (/swarm, /hive, /inbox, etc.)            │
│  ├── Skills (always-on-guidance, swarm-coordination)   │
│  ├── Agents (coordinator, worker)                      │
│  └── Hooks (SessionStart, PreCompact, etc.)            │
├─────────────────────────────────────────────────────────┤
│  swarm CLI (globally installed)                         │
│  ├── Hive tracker (.hive/ directory)                   │
│  ├── Hivemind semantic memory (LibSQL + Ollama)        │
│  └── Swarmmail coordination (embedded event store)     │
└─────────────────────────────────────────────────────────┘

Why This Architecture?

The main OpenCode swarm plugin bundles native dependencies (@libsql/client) which causes issues when Claude Code copies plugins to its cache. This plugin avoids bundling by delegating all tool execution to the globally installed swarm CLI.

Benefits:

• No native dependency issues
• Single source of truth (the CLI)
• Automatic updates when CLI is updated
• Tiny plugin size (~600KB bundled)

Development

# Install dependencies
bun install

# Build the MCP server bundle
bun run build

# Type check
bun run typecheck

License

MIT