Claude Code Agent Teams: The Complete Guide to Multi-Agent Development

The era of single-agent AI assistance is ending. Anthropic just shipped one of the most requested features for Claude Code: Agent Teams — the ability to spawn, coordinate, and orchestrate multiple Claude instances working together on complex tasks.

This isn't just "run multiple terminals." It's a fundamentally new paradigm where AI agents communicate with each other, claim tasks from shared queues, challenge each other's conclusions, and coordinate work without constant human supervision.

In this guide, we'll cover everything from basic setup to advanced patterns, with real examples you can use today.

What Are Agent Teams?

Agent Teams let you coordinate multiple Claude Code instances working in parallel. One session acts as the team lead, creating teammates, assigning work, and synthesizing results. Teammates are independent Claude instances, each with their own context window, working on their assigned tasks.

The key differentiator from Anthropic's existing subagents: teammates can talk to each other directly. They're not just workers reporting back to a central coordinator — they're collaborators that can:

• Message specific teammates or broadcast to the entire team
• Claim and complete tasks from a shared task list
• Challenge each other's findings (critical for debugging)
• Request plan approval before major changes
• Shut down gracefully when their work is done

┌──────────────────────────────────────────────────────────────┐
│                         YOU                                  │
│                          │                                   │
│                    ┌─────▼─────┐                             │
│                    │   LEAD    │ ◄── Coordinates work        │
│                    │  SESSION  │     Synthesizes results     │
│                    └─────┬─────┘                             │
│                          │                                   │
│          ┌───────────────┼───────────────┐                   │
│          │               │               │                   │
│    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐             │
│    │ TEAMMATE  │◄─►│ TEAMMATE  │◄─►│ TEAMMATE  │             │
│    │  (coder)  │   │(reviewer) │   │ (tester)  │             │
│    └───────────┘   └───────────┘   └───────────┘             │
│          │               │               │                   │
│          └───────────────┼───────────────┘                   │
│                          │                                   │
│                    ┌─────▼─────┐                             │
│                    │   TASK    │ ◄── Shared work queue       │
│                    │   LIST    │     with dependencies       │
│                    └───────────┘                             │
└──────────────────────────────────────────────────────────────┘

When Should You Use Agent Teams?

Agent Teams shine when parallel exploration adds value. They're not a silver bullet — coordination overhead and token costs are significant. Here's when they make sense:

✅ Perfect Use Cases

❌ When to Avoid

• Sequential tasks — One thing must finish before the next
• Same-file edits — Two teammates editing one file = merge hell
• Heavy dependencies — Tasks that constantly block each other
• Simple tasks — Overhead exceeds benefit

Agent Teams vs. Subagents

Both parallelize work, but they're fundamentally different:

Rule of thumb: Use subagents for quick, focused helpers. Use agent teams when workers need to discuss, debate, and coordinate.

Getting Started

1. Enable Agent Teams

Agent teams are experimental and disabled by default. Enable them via environment variable or settings:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or export in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. Create Your First Team

Just describe what you want in natural language. Claude handles the rest:

I'm building a CLI tool for tracking TODO comments in codebases. 
Create an agent team to explore this from different angles:
- One teammate on UX design
- One on technical architecture  
- One playing devil's advocate, finding holes in our approach

Claude will:

1. Create a team with a shared task list
2. Spawn three teammates with those roles
3. Have them explore the problem independently
4. Synthesize findings into recommendations
5. Clean up the team when finished

3. Choose a Display Mode

Two options for seeing your team work:

In-Process Mode (default)

• All teammates run in your main terminal
• Use Shift+Up/Down to select teammates
• Type to message them directly
• Works in any terminal

Split-Pane Mode

• Each teammate gets its own pane
• See everyone's output simultaneously
• Click into any pane to interact
• Requires tmux or iTerm2

// Force split-pane mode
{
  "teammateMode": "tmux"
}

Or per-session:

claude --teammate-mode in-process

Controlling Your Team

Assign Tasks

The lead coordinates based on your natural language instructions:

Create 4 teammates to refactor these modules in parallel.
Use Sonnet for each one.

Require Plan Approval

For risky changes, make teammates plan before implementing:

Spawn an architect teammate to refactor authentication.
Require plan approval before they make any changes.

The teammate enters read-only "plan mode," proposes an approach, and waits for lead approval before proceeding. If rejected, they revise and resubmit.

Use Delegate Mode

Sometimes the lead starts coding instead of delegating. Delegate mode restricts the lead to coordination-only tools:

1. Start a team first
2. Press Shift+Tab to enter delegate mode
3. Lead can only: spawn, message, shut down, manage tasks

Talk Directly to Teammates

Each teammate is a full Claude Code session. Message them anytime:

• In-process: Shift+Up/Down to select, then type
• Split-pane: Click into their pane

Hey security reviewer, also check for SQL injection in the user input handlers

Shut Down Teammates

Ask the researcher teammate to shut down

The lead sends a shutdown request. The teammate can approve (exit gracefully) or reject with an explanation if they're mid-task.

Clean Up

When done:

Clean up the team

This removes shared resources. Always shut down teammates first — cleanup fails if any are still running.

How It Works Under the Hood

Architecture

Storage Locations

~/.claude/
├── teams/{team-name}/
│   └── config.json          # Team metadata, member list
└── tasks/{team-name}/       # Shared task queue

Task States & Dependencies

Tasks flow through: pending → in progress → completed

Dependencies work automatically. If Task B depends on Task A:

• Task B stays pending until Task A completes
• When A finishes, B unblocks without manual intervention

Claiming Tasks

Two modes:

1. Lead assigns: Explicitly tell lead who does what
2. Self-claim: Teammates grab the next unassigned, unblocked task

File locking prevents race conditions when multiple teammates reach for the same task.

Token Reality Check

Agent teams are expensive. Each teammate has their own context window. Anthropic's data shows:

• Single agent: baseline
• Agent teams: ~15× more tokens than chat

This is worth it for complex research, parallel review, and feature development. For routine tasks, stick to single sessions or subagents.

Real-World Examples

1. Parallel Code Review

A single reviewer tends to focus on one issue type at a time. Split the concerns:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact  
- One validating test coverage
Have them each review and report findings.

Each reviewer applies a different lens to the same PR. The lead synthesizes across all three.

2. Debugging with Competing Hypotheses

When root cause is unclear, single agents anchor on their first theory. Fight this with adversarial investigation:

Users report the app exits after one message instead of staying connected.
Spawn 5 teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

The "scientific debate" structure forces teammates to actively challenge each other. The surviving theory is far more likely to be the actual root cause.

3. Cross-Layer Feature Implementation

Build OAuth login. Create a team with:
- Backend developer: implement OAuth controller and models
- Frontend developer: build login UI components
- Test writer: create integration tests (depends on backend)
Have them coordinate via the task list.

Each teammate owns their layer. The test writer's tasks block until backend is ready.

Best Practices

Give Teammates Rich Context

Teammates load project context (CLAUDE.md, MCP servers, skills) but not the lead's conversation history. Include everything they need in the spawn prompt:

Spawn a security reviewer with the prompt: "Review the auth module at 
src/auth/ for vulnerabilities. Focus on token handling, session management,
and input validation. The app uses JWT in httpOnly cookies. Report issues
with severity ratings."

Size Tasks Appropriately

Good task examples: a function, a test file, a review of one module.

Prevent File Conflicts

Two teammates editing the same file = disaster. Break work so each owns different files:

Teammate A owns: src/auth/*
Teammate B owns: src/api/*
Teammate C owns: tests/*

Monitor and Steer

Don't let the team run unattended for too long. Check progress, redirect bad approaches, synthesize findings as they arrive.

Start with Research

If you're new to agent teams, begin with non-coding tasks:

• Reviewing a PR
• Researching a library
• Investigating a bug

These show the value of parallel exploration without the coordination complexity of parallel implementation.

Troubleshooting

Teammates Not Appearing

1. In in-process mode, press Shift+Down — they might be running invisibly
2. Check if Claude thought the task was too simple for a team
3. For split panes, verify tmux is installed: which tmux
4. For iTerm2, ensure Python API is enabled in preferences

Too Many Permission Prompts

Teammate permissions bubble up to the lead, causing friction. Pre-approve common operations:

{
  "permissions": {
    "allow": ["Write(*)", "Bash(npm test)"]
  }
}

Lead Doing Work Instead of Delegating

Wait for your teammates to complete their tasks before proceeding

Or enable delegate mode (Shift+Tab).

Orphaned tmux Sessions

tmux ls
tmux kill-session -t <session-name>

Current Limitations

Agent teams are still experimental. Key constraints:

The Bigger Picture

Gartner predicts that by end of 2026, 40% of enterprise applications will include task-specific AI agents. Multi-agent inquiry has surged 1,445% in just one year.

Agent Teams in Claude Code isn't just a feature — it's a preview of how software development is evolving. The pattern of specialized agents collaborating on complex tasks, each with their own expertise and context, mirrors how high-performing human teams operate.

Today it's experimental, behind a feature flag. Tomorrow it'll be how we build software.

Quick Reference

Enable

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

Create Team

Create an agent team with [roles] to [task]

Control

Display Modes

{ "teammateMode": "in-process" }  // or "tmux" / "auto"

What's Next

• Subagents — Lightweight delegation for focused tasks
• Git Worktrees — Manual parallel sessions
• MCP Servers — Extend agents with custom tools

The future of coding isn't you or AI. It's you orchestrating a team of AI specialists, each doing what they do best, while you focus on the big picture.

Welcome to multi-agent development.

For the official documentation, visit code.claude.com/docs/en/agent-teams