Multi-agent orchestration plugin for Claude Code. Coordinate teams of agents with shared tasks, inter-agent messaging, and proven patterns for parallel reviews, pipelines, self-organizing swarms, and large-file analysis via the RLM pattern.
Official docs: Agent Teams
Before installing, make sure you have:
Install and authenticate Claude Code. See the quickstart guide.
claude --version # Verify installed, must be 1.0.33+Agent teams are experimental and disabled by default. Enable them by adding this to your settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Or set the environment variable directly:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1Split-pane mode lets you see all teammates working side-by-side. It requires tmux.
macOS:
brew install tmuxLinux (Debian/Ubuntu):
sudo apt install tmuxWhy tmux? Background agents need terminal multiplexing to run in visible, persistent panes. Without tmux, agents run in-process (invisible but functional). See docs/getting-started.md for details on display modes.
If you use iTerm2, install the it2 CLI for native split panes:
uv tool install it2
# Then: iTerm2 -> Settings -> General -> Magic -> Enable Python APIclaude /plugin install https://github.com/zircote/claude-team-orchestrationClone the repo and load it directly:
git clone https://github.com/zircote/claude-team-orchestration.git
claude --plugin-dir ./claude-team-orchestrationStart Claude Code and run:
/help
You should see swarm skills listed under the swarm: namespace:
swarm:orchestrating
swarm:team-management
swarm:task-system
swarm:messaging
swarm:agent-types
swarm:orchestration-patterns
swarm:spawn-backends
swarm:error-handling
swarm:rlm-pattern
swarm:jsonl-log-analyzer
| Problem | Fix |
|---|---|
| Skills don't appear | Restart Claude Code after installing |
swarm: prefix missing |
Verify .claude-plugin/plugin.json exists in the plugin directory |
| Agent teams not working | Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to 1 |
| Split panes not showing | Run which tmux to verify tmux is installed |
Here's a minimal example that spawns a parallel code review team with three specialists:
Create an agent team called "review" to review the src/ directory.
Spawn three reviewers in parallel:
- "security" using sdlc:security-reviewer — check for vulnerabilities
- "quality" using feature-dev:code-reviewer — check for bugs and performance
- "simplicity" using code-simplifier:code-simplifier — check for unnecessary complexity
Have each reviewer send findings to team-lead when done.
Synthesize all findings into a summary, then shut down the team.
What success looks like:
- Claude creates the team and spawns three agents
- Each agent reviews the code through its own lens (in parallel)
- Findings arrive as messages to the team lead
- The lead synthesizes a unified report
- The team shuts down cleanly
For more examples, see docs/patterns.md and skills/orchestration-patterns/examples/complete-workflows.md.
To get the most out of swarm orchestration, add the following to your project's CLAUDE.md (or your personal ~/.claude/CLAUDE.md). This tells Claude to prefer parallel agent teams over sequential work whenever appropriate:
## Always use swarm orchestration patterns (TeamCreate, Task with team_name, SendMessage, TaskCreate/TaskUpdate) when work is best executed by parallel specialist agents.
This means:
- Spawning teams with specialized teammates for parallelizable work
- Using the task list for coordination and progress tracking
- Leveraging SendMessage for inter-agent communication
- Preferring concurrent execution over sequential when tasks are independentWhy this matters: Without this instruction, Claude may default to running tasks sequentially or using simple subagents instead of coordinated teams — even when the plugin is installed. Adding this to CLAUDE.md ensures Claude proactively reaches for team orchestration when it would be beneficial.
Where to put it:
- Project-level (
CLAUDE.mdat your project root) — applies to all sessions in that project - Personal global (
~/.claude/CLAUDE.md) — applies to all your projects
All skills are available under the swarm: namespace.
| Skill | Command | Description |
|---|---|---|
| Orchestrating | swarm:orchestrating |
Primitives overview, lifecycle, quick reference. Start here. |
| Team Management | swarm:team-management |
Create teams, spawn teammates, delegate mode, permissions, shutdown, cleanup |
| Task System | swarm:task-system |
Create tasks, set dependencies, claim work, track progress |
| Messaging | swarm:messaging |
Direct messages, broadcasts, shutdown requests, plan approvals |
| Agent Types | swarm:agent-types |
Built-in and plugin agents, selection guide, capabilities |
| Orchestration Patterns | swarm:orchestration-patterns |
7 patterns: parallel specialists, pipelines, swarms, research+implement, plan approval, refactoring, RLM |
| Spawn Backends | swarm:spawn-backends |
In-process, tmux, iTerm2 backends, auto-detection, configuration |
| Error Handling | swarm:error-handling |
Common errors, quality gate hooks, known limitations, recovery strategies |
| RLM Pattern | swarm:rlm-pattern |
Content-aware chunked analysis of large files and directories using RLM pattern |
| JSONL Log Analyzer | swarm:jsonl-log-analyzer |
Schema-aware analysis of large JSONL log files with automated field discovery and jq recipes |
| Guide | Description |
|---|---|
| Getting Started | End-to-end walkthrough from install to first team run |
| Agent Types | Which agents are available and when to use each |
| Patterns | Orchestration patterns with guidance on when to pick which |
| RLM Examples | Copy-paste example prompts for every RLM mode |
| Concepts | How teams, patterns, and RLM content processing work internally |
| Reference | Primitives, message types, task fields, configuration, and API lookup tables |
| Troubleshooting | Common failures and fixes |
This plugin is based on the Claude Code Swarm Orchestration Skill by @kieranklaassen. The original monolithic gist has been decomposed into modular, maintainable skills that can be independently loaded, updated, and extended.