Claude Code Agent Teams: Run Multiple Claudes in Parallel

Problem: Complex multi-file tasks need agents that talk to each other, not just report back to a central coordinator. Subagents work in isolation. They can't share findings, challenge assumptions, or coordinate directly. When you need real collaboration between AI workers, subagents hit a wall.

Quick Win: Enable Agent Teams and spawn a collaborative team in one prompt:

# Add to your environment or settings.json
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Then tell Claude:

Create an agent team to refactor the payment module. Spawn three teammates:
one for the API layer, one for the database migrations, one for test coverage.
Have them coordinate through the shared task list.

Claude creates a team lead, spawns three independent teammates, and coordinates their work through a shared task list and direct messaging. Each teammate owns their scope. No conflicts, no isolation.

Note on terminology: This post covers Claude Code's native Agent Teams feature, an experimental built-in system for multi-agent collaboration. If you're looking for DIY builder-validator patterns using the Task tool, see team orchestration with builder-validator chains. Both approaches enable multi-agent workflows, but they work very differently under the hood.

What Are Agent Teams?

Agent Teams is an experimental feature that lets you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.

The key difference from subagents is communication. Subagents run within a single session and can only report results back to the main agent. That is it. They can't message each other, share discoveries mid-task, or coordinate without the main agent acting as intermediary. Agent Teams removes that bottleneck. You can interact with individual teammates directly without going through the lead. Teammates message each other, claim tasks from a shared list, and work through problems collaboratively.

Think of it this way: subagents are contractors you send on errands. Agent Teams is a project team sitting in the same room, each working on their piece while staying in sync through conversation.

When to Use Agent Teams

Agent Teams are most effective for tasks where parallel exploration adds real value. The strongest use cases are:

• Research and review: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings
• New modules or features: teammates can each own a separate piece without stepping on each other
• Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster
• Cross-layer coordination: changes that span frontend, backend, and tests, each owned by a different teammate

Agent Teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.

Subagents vs Agent Teams

Both let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:

Use subagents when you need quick, focused workers that report back. Use Agent Teams when teammates need to share findings, challenge each other, and coordinate on their own.

For more on subagent patterns, see sub-agent best practices.

How to Enable Agent Teams

Agent Teams is disabled by default. Set one environment variable to turn it on.

In your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or add it to your settings.json for persistence across sessions:

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

Once enabled, you can ask Claude to create a team and it handles the rest.

Starting Your First Agent Team

After enabling, describe the task and team structure in natural language. Claude creates the team, spawns teammates, and coordinates work.

Example prompt:

I'm designing a CLI tool that helps developers track TODO comments across their
codebase. Create an agent team to explore this from different angles: one teammate
on UX, one on technical architecture, one playing devil's advocate.

Claude creates a team with a shared task list, spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to clean up the team when finished.

Teams can also be created by Claude's initiative. If Claude determines your task would benefit from a team, it may propose creating one. But you stay in control. Claude will not create a team without your approval.

Specifying Teammates and Models

Claude decides the number of teammates based on the complexity of your task, or you can specify exactly what you want:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Architecture: How Teams Work

An Agent Team has four components working together:

Teams and their configuration live locally:

• Team config: ~/.claude/teams/{team-name}/config.json
• Task list: ~/.claude/tasks/{team-name}/

The team config contains a members array with each teammate's name, agent ID, and agent type.

Context and Communication

Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular Claude Code session: your CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over.

Communication works through several channels:

• Automatic message delivery: when teammates send messages, they are delivered automatically to recipients
• Idle notifications: when a teammate finishes and stops, they automatically notify the lead
• Shared task list: all agents can see task status and claim available work
• Message: send to one specific teammate
• Broadcast: send to all teammates simultaneously (use sparingly, since costs scale with team size)

Permissions

Teammates start with the lead's permission settings. If the lead runs with --dangerously-skip-permissions, all teammates do too. After spawning, you can change individual teammate modes, but you cannot set per-teammate modes at spawn time.

Display Modes: Watching Your Team Work

Agent Teams supports two ways to view what's happening.

In-Process Mode (Default)

All teammates run inside your main terminal. You see the lead's output by default and can switch between teammates:

• Shift+Up/Down: Select a teammate to view or message
• Enter: View a teammate's full session
• Escape: Interrupt a teammate's current turn
• Ctrl+T: Toggle the task list

This works in any terminal. No extra setup required. It is the default behavior.

Split Pane Mode

Each teammate gets its own terminal pane. You see everyone's output simultaneously and click into any pane to interact with their session directly. This requires tmux or iTerm2.

tmux has known limitations on certain operating systems and traditionally works best on macOS. Using tmux -CC in iTerm2 is the suggested entrypoint into tmux.

To configure display mode, set teammateMode in your settings.json:

{
  "teammateMode": "in-process"
}

The three options:

• "auto" (default): Uses split panes if you're already inside a tmux session, otherwise falls back to in-process
• "tmux": Enables split panes, auto-detects between tmux and iTerm2 based on your terminal
• "in-process": Forces all teammates into the main terminal

You can also override per-session with a flag:

claude --teammate-mode in-process

Split-pane mode requires either tmux or iTerm2 with the it2 CLI.

Delegate Mode: Keep the Lead Focused

Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. This defeats the purpose of having a team.

Press Shift+Tab to cycle into delegate mode after starting a team. This restricts the lead to coordination-only tools: spawning teammates, messaging, shutting them down, and managing tasks. The lead can't touch code directly. It focuses entirely on orchestration.

Use delegate mode when you want the lead to stay in its coordination role and stop doing implementation work.

Plan Approval: Review Before Execution

For complex or risky tasks, require teammates to plan before they implement anything. The teammate works in read-only plan mode until the lead approves their approach.

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

The workflow:

1. Teammate receives the task and works in read-only mode
2. Teammate creates a plan and sends a plan approval request to the lead
3. Lead reviews the plan and either approves or rejects with feedback
4. If rejected, the teammate stays in plan mode, revises, and resubmits
5. Once approved, the teammate exits plan mode and begins implementation

The lead makes approval decisions autonomously. Influence its judgment through your initial prompt: "only approve plans that include test coverage" or "reject plans that modify the database schema."

Talking to Teammates Directly

Each teammate is a full, independent Claude Code session. You can message any teammate directly without going through the lead.

In-process mode: Use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.

Split-pane mode: Click into a teammate's pane to interact with their session directly.

Task Assignment and Claiming

The shared task list coordinates all work. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.

The lead can assign tasks explicitly, or teammates can self-claim available work. After finishing a task, a teammate picks up the next unassigned, unblocked task on its own.

Task claiming uses file locking to prevent race conditions where two teammates grab the same task.

For more on task coordination patterns, see task distribution.

Shutting Down Teammates

To shut down a specific teammate, tell the lead:

Ask the researcher teammate to shut down

The lead sends a shutdown request. The teammate can approve (exiting gracefully) or reject with an explanation. Teammates finish their current request or tool call before shutting down, so this can take some time.

Cleaning Up the Team

When work is finished, tell the lead:

Clean up the team

This removes shared team resources. The lead checks for active teammates and fails if any are still running, so shut them all down first.

Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly.

Use Case Examples

Parallel Code Review

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 works from the same PR but applies a different filter. The lead synthesizes findings into a comprehensive review that a single reviewer would have missed by focusing on only one concern at a time.

Investigating with Competing Hypotheses

Users report the app exits after one message instead of staying connected.
Spawn 5 agent 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 debate structure fights anchoring bias. Multiple independent investigators actively trying to disprove each other means the surviving theory is more likely correct. Instead of testing theories sequentially (where you tend to stop at the first plausible explanation), parallel investigation with active challenge produces more reliable conclusions.

Token Usage

Agent Teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. Communication adds to the cost because every message between teammates consumes tokens in both the sender's and receiver's context windows. Broadcasting multiplies cost by the number of teammates receiving the message.

For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective.

Best Practices

• Give teammates enough context: include task-specific details in the spawn prompt so teammates don't start blind
• Size tasks appropriately: not too small, not too large. Aim for self-contained units with clear deliverables, roughly 5-6 tasks per teammate
• Wait for teammates to finish before proceeding: don't let the lead race ahead while teammates are still working
• Start with research and review before implementation: build intuition for when teams add value before applying them to implementation-heavy workflows
• Avoid file conflicts: each teammate should own different files. Two teammates editing the same file leads to overwrites
• Monitor and steer: check progress regularly and redirect approaches that are going off track

Troubleshooting

Current Limitations

Agent Teams is experimental. These constraints are worth knowing before you commit to a team-based workflow:

• No session resumption: in-process teammates are not restored when using /resume or /rewind. After resuming, the lead may try to message teammates that no longer exist. Tell it to spawn replacements
• Task status can lag: teammates sometimes forget to mark tasks as completed, blocking dependent work. Check manually if something looks stuck
• Slow shutdown: teammates finish their current request or tool call before shutting down. This can take time
• One team per session: a lead manages one team at a time. Clean up the current team before starting another
• No nested teams: teammates cannot spawn their own teams. Only the lead manages the team hierarchy
• Fixed lead: the session that creates the team stays the lead for its lifetime. You cannot promote a teammate or transfer leadership
• Permissions set at spawn: all teammates start with the lead's permission settings. You can change individual modes after spawning, but not at spawn time
• Split panes require tmux or iTerm2: split-pane mode is not supported in other terminals
• CLAUDE.md works normally: teammates load project instructions the same way any session does

Getting Started

If you are new to Agent Teams, start with a low-risk task that demonstrates the value without the complexity of parallel implementation. Pick a PR that needs review, enable Agent Teams, then:

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.

Three reviewers, three lenses, one comprehensive review. You will see how teammates work through the task list, communicate findings, and deliver results.

From there, move to debugging tasks where competing hypotheses benefit from parallel investigation. Then try implementation tasks where teammates own separate files and coordinate through messaging.

Agent Teams extends what you can do with subagents and task distribution by adding the collaboration layer that isolated agents lack. Combined with builder-validator patterns for quality assurance and well-designed agent architectures, you have a full spectrum of multi-agent approaches: from simple parallel execution to coordinated team collaboration. For keeping context manageable across long-running team sessions, apply the same strategies you would with any multi-agent workflow.