# Claude Swarm — Multi-Agent Orchestration with SDK

> Python-based multi-agent orchestration built on Claude Agent SDK. Opus decomposes tasks, Haiku workers execute in parallel waves with real-time TUI dashboard and budget control.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
git clone https://github.com/affaan-m/claude-swarm
cd claude-swarm
pip install -e .
```

```yaml
# swarm.yaml
name: refactor-swarm
leader:
  model: opus
workers:
  count: 4
  model: haiku
budget:
  max_cost: 5.00
```

```bash
claude-swarm run "Refactor the authentication module"
```

## What is Claude Swarm?

Claude Swarm is a Python-based multi-agent orchestration system built on the Claude Agent SDK. It uses a three-phase architecture: Opus 4.6 decomposes tasks into dependency graphs, parallel waves of Haiku workers execute them with pessimistic file locking, and Opus reviews all outputs for integration issues. Features a real-time htop-style TUI dashboard.

**Answer-Ready**: Claude Swarm orchestrates multiple Claude agents with Opus decomposition and Haiku worker execution. Three-phase architecture: decompose → execute in parallel waves → quality gate. Real-time TUI dashboard, budget enforcement, YAML topology, session replay.

**Best for**: Teams orchestrating multiple Claude agents for large codebases. **Works with**: Claude Agent SDK, Claude API. **Setup time**: Under 5 minutes.

## Architecture

### Three Phases

```
Phase 1: DECOMPOSE (Opus 4.6)
  Task → Dependency Graph → Parallel Waves

Phase 2: EXECUTE (Haiku Workers)
  Wave 1: [task-a, task-b] (parallel, no deps)
  Wave 2: [task-c] (depends on a+b)
  Wave 3: [task-d, task-e] (depends on c)

Phase 3: QUALITY GATE (Opus 4.6)
  Review all outputs → Flag integration issues
```

### Key Features

| Feature | Details |
|---------|---------|
| TUI Dashboard | htop-style real-time monitoring |
| File Locking | Pessimistic locks prevent conflicts |
| Budget Control | Hard cost limits per swarm run |
| Session Replay | JSONL recording/playback |
| YAML Config | Declarative swarm topology |
| Retry Logic | Automatic task retry on failure |
| Demo Mode | Dry-run without API calls |

### Real-Time Dashboard

```
┌─ Claude Swarm ────────────────────────────┐
│ Budget: $1.23 / $5.00  Tasks: 3/7        │
│                                           │
│ Worker-1  ████████░░  task-a  [running]   │
│ Worker-2  ██████████  task-b  [done]      │
│ Worker-3  ░░░░░░░░░░  task-c  [waiting]   │
│ Worker-4  ████░░░░░░  task-d  [running]   │
└───────────────────────────────────────────┘
```

## FAQ

**Q: How does it prevent file conflicts?**
A: Pessimistic file locking — only one worker can modify a file at a time. Others wait.

**Q: Can I limit costs?**
A: Yes, set `budget.max_cost` in YAML. Swarm stops when budget is reached.

**Q: Does it work with Claude Code?**
A: Claude Swarm uses the Claude Agent SDK directly, not Claude Code. It is a separate orchestration tool.

## Source & Thanks

> Created by [affaan-m](https://github.com/affaan-m). Licensed under MIT.
>
> [affaan-m/claude-swarm](https://github.com/affaan-m/claude-swarm)

<!-- ZH -->


## Quick Start

```bash
git clone https://github.com/affaan-m/claude-swarm
pip install -e .
claude-swarm run "refactor the auth module"
```

## What is Claude Swarm?

A multi-agent orchestration system built on the Claude Agent SDK. Opus decomposes tasks, Haiku Workers execute in parallel, Opus reviews for quality.

**In one sentence**: Claude multi-agent orchestration — Opus decomposes + Haiku executes in parallel + quality gate, real-time TUI dashboard, budget control, YAML config.

**For**: Teams orchestrating multiple Claude agents on large codebases.

## Architecture

Three stages: decompose (Opus) → parallel execution (Haiku) → quality gate (Opus).

## FAQ

**Q: How are conflicts prevented?**
A: Pessimistic file locking — only one worker modifies a file at a time.

## Source & Thanks

> [affaan-m/claude-swarm](https://github.com/affaan-m/claude-swarm) — MIT

---
Source: https://tokrepo.com/en/workflows/claude-swarm-multi-agent-orchestration-sdk-c55ce837
Author: Agent Toolkit