Agent Teams: Multi-Agent Orchestration

What Are Agent Teams?

Agent teams are multiple Claude instances working together on a task. One agent leads — decomposing work, assigning tasks, and integrating results. The others are teammates — specialized workers that implement their assigned tasks in parallel.

This is the most powerful and most expensive feature in Claude Code. It's designed for large, complex tasks that benefit from parallel work: migrating a codebase, implementing a feature across many files, or running comprehensive reviews.

Enabling Agent Teams

Agent teams are experimental. Enable them with:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

How Teams Work

1. You Describe the Task

"Migrate all API endpoints from Express to Fastify. There are 15 route files
in src/routes/. Each needs to be converted to Fastify syntax, and their tests
need to be updated."

2. The Lead Decomposes

The lead agent (Opus) analyzes the task and creates a plan:

Lead Agent Plan:
├── Teammate 1: Convert src/routes/auth.ts + update tests
├── Teammate 2: Convert src/routes/users.ts + update tests
├── Teammate 3: Convert src/routes/orders.ts + update tests
├── Teammate 4: Convert src/routes/payments.ts + update tests
├── Teammate 5: Convert src/routes/products.ts + update tests
└── Lead: Review all conversions, fix conflicts, update shared code

3. Teammates Work in Parallel

Each teammate gets its own context window, instructions, and potentially its own worktree. They work simultaneously — while Teammate 1 converts auth routes, Teammate 2 converts user routes.

4. Lead Integrates

When teammates finish, the lead reviews their work, resolves conflicts, and integrates the results.

Team Architecture

┌─────────────────┐
│   Lead Agent    │  Model: Opus (planning + coordination)
│   (Coordinator)  │  Role: Decompose, assign, integrate
└────────┬────────┘
         │
    ┌────┼────┬────────��
    ▼    ▼    ▼        ▼
┌──────┐┌──────┐┌──────┐┌──────┐
│Team 1││Team 2││Team 3││Team 4│  Model: Sonnet (implementation)
│      ││      ││      ││      │  Role: Implement assigned tasks
└──────┘└──────┘└──────┘└──────┘

Communication

Direct Messages (1:1)

Send a message to a specific teammate:

Shift+Up / Shift+Down → Select teammate
Type your message → Send

Example:

[To Teammate 2]: "The user routes need to handle the new pagination
format. Check src/lib/pagination.ts for the interface."

Broadcasts (to all)

Send a message to all teammates at once:

[Broadcast]: "All teammates: make sure to use the new error handler
from src/lib/errors.ts, not the old one."

Agent-to-Agent

Teammates can message each other and the lead:

[Teammate 1 → Lead]: "I've finished the auth routes. Found a shared
utility that needs updating — should I handle it or assign it?"

[Lead → Teammate 1]: "Go ahead and update it. I'll tell the others
to pull your changes."

Setting Up a Team

Using Custom Agents as Teammates

Your custom agents become available as teammates:

.claude/agents/
├── security-reviewer.md    → Available as teammate
├── test-writer.md          → Available as teammate
├── doc-writer.md           → Available as teammate

When the lead decomposes a task, it can assign security review to the security-reviewer agent, test writing to the test-writer, and documentation to the doc-writer.

Team Configuration

In your agent frontmatter, you can configure team behavior:

---
name: Feature Implementer
description: Implements features in assigned files
model: sonnet
isolation: worktree
permissionMode: acceptEdits
---

The isolation: worktree is particularly important for teams — each teammate works in its own worktree, preventing file conflicts.

When to Use Agent Teams

Good Use Cases

• Large migrations: Converting 20+ files from one pattern to another
• Feature implementation across modules: A feature that touches auth, API, database, and tests
• Comprehensive reviews: Security + quality + performance review in parallel
• Test generation at scale: Generating tests for an entire untested module

Bad Use Cases

• Simple tasks: A single file change doesn't need a team
• Quick fixes: Bug fixes are faster with a single session
• Exploration: Understanding code is faster with one agent
• Cost-sensitive work: Teams are ~7x more expensive

The Cost Reality

Agent teams are expensive. Here's the math:

Single agent session (50 messages):
  ~50,000-150,000 tokens
  
Agent team (lead + 4 teammates):
  Lead planning phase:     ~200,000 tokens (decomposition, coordination)
  4 teammates × 50,000:   ~200,000 tokens (parallel implementation)
  Lead integration phase:  ~100,000 tokens (review, merge, conflicts)
  Total:                   ~500,000 tokens

That's roughly 3-5x a single agent for the same total work, plus the coordination overhead. The trade-off is parallel execution — four teammates finish in 1/4 the time of a single agent doing everything sequentially.

Use teams when time savings justify the token cost.

Best Practices

1. Clear Task Boundaries

Give the lead a task with clear boundaries between subtasks:

# Good: Clear boundaries
"Migrate all route files from Express to Fastify. Each file in src/routes/ 
is independent. Convert the file and update its test."

# Bad: Unclear boundaries
"Improve the codebase" (How does the lead decompose this?)

2. Use Worktree Isolation

Configure teammates with isolation: worktree to prevent file conflicts:

---
isolation: worktree
---

3. Set Max Turns

Prevent teammates from running too long:

---
maxTurns: 25
---

4. Use the Right Models

Lead should be Opus (planning). Teammates should be Sonnet (implementation).

# Lead
model: opus

# Teammates
model: sonnet

Key Takeaway

Agent teams enable parallel multi-agent work on large tasks. The lead (Opus) decomposes and coordinates; teammates (Sonnet) implement in parallel. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Use Shift+Up/Down for direct messages, broadcasts for team-wide instructions. The trade-off is ~7x token cost for parallel execution. Use teams for large migrations, cross-module features, and scale-out reviews — not for simple tasks where a single session is faster and cheaper.