# Multi-Agent Patterns

## Why This Matters

Subagents are the most powerful tool for managing context — they explore in a separate context window, keeping the main conversation clean. However, multi-agent workflows are overkill for 95% of tasks and currently expensive.

## Current State

- Built-in subagent support available (Explore, Plan, general-purpose)
- No custom orchestration
- No multi-terminal patterns

## Patterns (Simplest to Most Complex)

### 1. Built-in Subagents (Already Available)
Delegate research, exploration, and file searches to subagents. They run in separate context windows and return summaries. This is the easiest win — just use the Agent tool more deliberately.

### 2. Git Worktrees for Parallel Work
Use `git worktree` to let multiple Claude instances work on separate branches without conflicts. Each instance has its own working directory but shares the git history.

### 3. The 4-Terminal Pattern
Simple but effective: 4 specialised Claude Code agents in separate VS Code / tmux terminals with distinct roles (e.g., planner, implementer, tester, reviewer). Often beats complex orchestrators.

### 4. Master-Clone Architecture
Rather than custom subagents with rigid workflows, use Claude's built-in `Task(...)` to spawn general-agent clones. Put key context in CLAUDE.md and let the agent orchestrate delegation dynamically.

### 5. Container Isolation
Local Claude Code controls another instance inside a Docker container via tmux — sandboxed autonomous worker for risky/destructive operations.

## Orchestration Tools

| Tool | Description |
|---|---|
| **Claude Squad** | Terminal app managing multiple Claude Code agents in separate workspaces |
| **Happy Coder** | Spawn and control multiple Claude Codes with push notifications |
| **Claude Swarm** | Launch a Claude Code session connected to a swarm of other agents |
| **Claude MPM** | 47+ specialised agents with PM orchestration and automatic task routing |

## When NOT to Use Multi-Agent

- Simple, single-file changes
- Tasks that take less than a few minutes
- When context window is not a constraint
- When the coordination overhead exceeds the work itself

The community consensus: master the single-agent workflow first. Multi-agent adds complexity and cost that only pays off for genuinely parallel, independent workstreams.