← Back to main site
Agent Orchestration

Run teams of Claude Code agents in parallel

Three approaches to orchestrate multiple Claude Code instances — from simple parallel sessions to full-scale autonomous coordination with 20+ agents.

NATIVE

Agent Teams

Built into Claude Code · Experimental

First-party multi-agent system. One lead spawns teammates that communicate via shared task lists and peer-to-peer messaging. Richest coordination model with dependency tracking, plan approval, and file locking. Best for collaborative work where agents need to discuss, debate, or build on each other's output.

3-5 agents peer messaging shared tasks ~4x token cost
TEAM LEAD Spawns & coordinates teammates EXPERIMENTAL SHARED TASK LIST ~/.claude/tasks/ • file locking • deps MAILBOX Peer & broadcast msgs TEAMMATE A Own 200k context window Claims tasks autonomously TEAMMATE B Own 200k context window Claims tasks autonomously TEAMMATE C Own 200k context window Claims tasks autonomously DISPLAY LAYER tmux split panes | In-process (Shift+Down) create claim peer msg peer msg
Lead
Teammates
Task List
Mailbox
Display
Peer-to-peer
Data flow

Data Flow

Lead creates tasks → Tasks appear in shared list → Teammates claim via file lock → Work completes → Dependencies auto-unblock → Lead synthesizes results.

Communication

Bidirectional: teammates message each other directly (not just report to lead). Broadcast sends to all. Idle notifications automatic.

Isolation

Each teammate: own 200k context window. Shared filesystem but NOT conversation history. CLAUDE.md is the shared context mechanism.

Cost

~4x solo for 3 teammates (~800k tokens). Each is a full Claude instance. Mix models (Opus/Sonnet/Haiku) to optimize cost.

Official Agent Teams documentation →
OPEN SOURCE

Claude Squad

TUI app · Git worktree isolation · 6k+ stars

Terminal UI for managing parallel AI sessions. Each agent runs in its own tmux session and git worktree — fully isolated branches, zero file conflicts. You coordinate. Supports Claude, Aider, Codex, Gemini, and custom tools. Best for independent parallel tasks where agents don't need to talk to each other.

5-10 agents git isolation multi-agent CLI YOLO mode
HUMAN INTERFACE SESSIONS ISOLATION ✕ ✕ YOU (HUMAN) Decide tasks, review, merge CLAUDE SQUAD TUI session list + preview | n/Enter/s/c/r/d/q STABLE tmux session Claude Code agent auth-refactor tmux session Aider agent fix-navbar tmux session Codex agent update-docs Git Worktree branch: cs/auth isolated file copy Git Worktree branch: cs/navbar isolated file copy Git Worktree branch: cs/docs isolated file copy No inter-agent communication — fully independent manage checkout
Human
TUI
tmux sessions
Git worktrees
✕No communication

Data Flow

Human creates session via TUI → spawns tmux + git worktree → agent works in isolation → human reviews diff → merges branch.

Double Isolation

tmux isolates the terminal session. Git worktree isolates the filesystem. Each agent on its own branch. Zero file conflict risk.

Multi-Agent

Supports Claude, Aider, Codex, Gemini CLI, OpenCode, Qwen, and custom tools. Mix different AI agents per session.

YOLO Mode

Auto-accept permissions for unattended work. Safe: changes stay on isolated branches. Review diff before merging.

Claude Squad on GitHub →
OPEN SOURCE

Gas Town

"Kubernetes for AI Agents" · by Steve Yegge · 10k+ stars

Full orchestration platform with a Mayor agent that decomposes goals, spawns workers, and handles failures. All state is git-backed — agent identity, tasks, and progress survive crashes. Manager hierarchy enables structured delegation at scale. Best for large complex projects requiring 10+ agents with crash recovery and automated coordination.

20-30 agents crash recovery Mayor AI coord agent hierarchy
Rig: .gastown/ (git-backed) COORDINATOR WORK BUNDLES TASKS AGENTS PERSISTENCE MAYOR Decomposes goals • Spawns agents • Monitors CONVOY A Auth Refactor (epic) CONVOY B API Redesign (epic) Bead 1 Fix token refresh Bead 2 Add OAuth2 Bead 3 REST v2 Bead 4 GraphQL schema MANAGER POLECAT Coordinates sub-team Can spawn workers Worker Polecat Persistent identity Worker Polecat Persistent identity Worker Polecat Persistent identity Hook (git state) Hook (git state) Hook (git state) Crash recovery: Heartbeat timeout → Respawn from Hook decompose assign spawn
Mayor / Convoys
Beads (tasks)
Manager
Workers
Hooks (persistent)
Data flow

Data Flow

Goal → Mayor decomposes into Convoys (epics) → Convoys hold Beads (tasks) → Manager assigns to Workers → Workers persist progress to Hooks → Merge.

Crash Recovery

Session dies? Heartbeat times out (5 min). Identity + task + progress survive in git-backed Hooks. New session reads Hook and resumes.

Hierarchy

Mayor → Manager Polecats → Worker Polecats. Three delegation levels. Managers coordinate sub-teams independently. Max depth configurable.

Scale

20-30 concurrent agents. Configurable limits prevent fork bombs. Dolt for structured state. Git worktree per agent for isolation.

Gas Town on GitHub →

Quick Comparison

Feature Agent Teams Claude Squad Gas Town
Scale3-5 agents5-10 agents20-30 agents
Agent CommunicationPeer-to-peerNoneMailboxes
Task CoordinationAutomated (lead)HumanAutomated (Mayor)
Crash RecoveryNonePartial (tmux)Full (git-backed)
Setup ComplexityLow (feature flag)Low (brew install)High (Go + Dolt)
Git IsolationManualAutomatic worktreesAutomatic worktrees
Agent HierarchyFlatFlatMulti-level

Which one should you use?

Do agents need to talk to each other?
├─ NO  → Claude Squad  (simple, isolated, human-managed)
└─ YES → How many agents?
   ├─ 3-5  → Agent Teams  (native, peer messaging, shared tasks)
   └─ 10+  → Need crash recovery?
      ├─ YES → Gas Town     (persistent state, Mayor coordination)
      └─ NO  → Agent Teams  (scale up with multiple leads)