swarm

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

---

Prerequisites

Before installing, make sure you have:

Claude Code CLI

Install and authenticate Claude Code. See the quickstart guide.

claude --version   # Verify installed, must be 1.0.33+

Enable Agent Teams

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=1

tmux (recommended)

Split-pane mode lets you see all teammates working side-by-side. It requires tmux.

macOS:

brew install tmux

Linux (Debian/Ubuntu):

sudo apt install tmux

Why 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.

iTerm2 (optional, macOS only)

If you use iTerm2, install the it2 CLI for native split panes:

uv tool install it2
# Then: iTerm2 -> Settings -> General -> Magic -> Enable Python API

---

Installation

From GitHub

claude /plugin install https://github.com/zircote/claude-team-orchestration

From local directory

Clone the repo and load it directly:

git clone https://github.com/zircote/claude-team-orchestration.git
claude --plugin-dir ./claude-team-orchestration

Verify installation

Start 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

Troubleshooting setup

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

---

Quick Start

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:

1. Claude creates the team and spawns three agents
2. Each agent reviews the code through its own lens (in parallel)
3. Findings arrive as messages to the team lead
4. The lead synthesizes a unified report
5. The team shuts down cleanly

For more examples, see docs/patterns.md and skills/orchestration-patterns/examples/complete-workflows.md.

---

Recommended CLAUDE.md Configuration

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: