# 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 as a script file and run:

## 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 -->

## 快速使用

```bash
git clone https://github.com/affaan-m/claude-swarm
pip install -e .
claude-swarm run "重构认证模块"
```

## 什么是 Claude Swarm？

基于 Claude Agent SDK 的多 Agent 编排系统。Opus 分解任务，Haiku Worker 并行执行，Opus 质量审查。

**一句话总结**：Claude 多 Agent 编排，Opus 分解 + Haiku 并行执行 + 质量门，实时 TUI 仪表盘，预算控制，YAML 配置。

**适合人群**：编排多个 Claude Agent 处理大型代码库的团队。

## 架构

三阶段：分解（Opus）→ 并行执行（Haiku）→ 质量门（Opus）。

## 常见问题

**Q: 怎么防冲突？**
A: 悲观文件锁，同一时间只有一个 Worker 修改文件。

## 来源与致谢

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

---
Source: https://tokrepo.com/en/workflows/c55ce837-5652-4027-a7b4-cb244acb488d
Author: Agent Toolkit