Claude Code agent teams represent a paradigm shift in AI-assisted development. Instead of a single AI agent working through tasks sequentially, you can now orchestrate multiple Claude Code instances working in parallel — powered by Claude Opus 4.6—researching, debugging, and building while coordinating with each other. This complete guide covers everything you need to know about Claude Code agent teams documentation, from initial setup to advanced configuration.

What Are Claude Code Agent Teams?

Agent teams let you coordinate multiple Claude Code sessions working together on complex tasks. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and can communicate directly with each other.

This is fundamentally different from Claude Code's existing subagents. While subagents report results back to a single parent and cannot communicate with each other, agent team members message directly, challenge each other's findings, and self-coordinate through a shared task list.

Agent Teams Architecture

Component Role Team Lead Your main Claude Code session that creates the team, spawns teammates, assigns tasks, and synthesizes results Teammates Separate Claude Code instances with their own context windows, working independently on assigned tasks Task List Shared work items with dependency tracking. Tasks auto-unblock when dependencies completeMailboxMessaging system enabling direct communication between agents—not just reporting to the lead

Agent Teams vs Subagents: When to Use Which

Understanding the difference between agent teams and subagents is crucial for choosing the right approach. Here's a detailed comparison:

FeatureSubagentsAgent TeamsContextOwn window; results return to callerOwn window; fully independentCommunicationReport back to main agent onlyTeammates message each other directlyCoordinationMain agent manages everythingShared task list with self-coordinationBest ForFocused tasks where only the result mattersComplex work requiring discussion and collaborationToken CostLower—results summarized backHigher—each teammate is a separate Claude instance (~5x)

Use subagents when: You need quick, focused workers that report back. "Go research X and tell me what you find."

Use agent teams when: Workers need to share findings, challenge each other, and coordinate autonomously. "Investigate this bug from three angles and debate which theory is correct."

Step-by-Step Setup Guide

Agent teams are currently in research preview and disabled by default. Follow these steps to enable and configure them.

Step 1: Enable Agent Teams

You have three options to enable agent teams:

Option A: Using settings.json (Recommended)

Add the experimental flag to your Claude Code settings file. This persists across sessions:

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

Option B: Environment Variable

Add to your shell profile (.bashrc, .zshrc) for permanent access:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Option C: Per-Session

For testing without committing to the change:

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Step 2: Choose Your Display Mode

Agent teams support two display modes for monitoring your team:

In-process mode (default): All teammates run inside your main terminal. Use Shift+Up/Down to select a teammate, Enter to view their session, Escape to interrupt, and Ctrl+T to toggle the task list. Works in any terminal.

Split-pane mode: Each teammate gets its own terminal pane via tmux or iTerm2. See everyone's output simultaneously. Requires additional setup.

Configure in settings.json:

{
  "teammateMode": "in-process"  // or "tmux" for split panes
}

Or override per-session:

claude --teammate-mode in-process

Note: Split-pane mode does NOT work in VS Code integrated terminal, Windows Terminal, or Ghostty. Use in-process mode for these terminals.

Step 3: Spawn Your First Team

Once enabled, tell Claude in natural language what team structure you want. Claude handles spawning and coordination:

I'm refactoring the auth module. Create an agent team:
- One teammate on the backend JWT logic
- One on the frontend session handling  
- One writing integration tests

Claude spawns the team, creates a shared task list, and starts coordinating automatically. No YAML configs or boilerplate needed.

Configuration Examples

Example 1: Parallel Code Review

A single reviewer gravitates toward one type of issue. Three reviewers with different lenses catch what one misses:

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.

Example 2: Debugging with Competing Hypotheses

This is the killer use case. Single agents find one plausible explanation and stop. Multiple agents arguing find the right explanation:

Production API is returning 500s intermittently. Create a debugging team:
- Hypothesis 1: Database connection pool exhaustion
- Hypothesis 2: Race condition in the caching layer
- Hypothesis 3: Memory leak in the request handler

Have them share evidence and argue which theory fits the logs.

Example 3: Multi-Module Feature Development

For features spanning multiple layers, each teammate owns one layer with no file conflicts:

Create an agent team for the new payment feature:
- Teammate 1: Backend API endpoints and database schema
- Teammate 2: Frontend components and state management
- Teammate 3: E2E tests and integration tests

Use Sonnet for each teammate.

Example 4: Research and Exploration

Perfect for exploring different approaches before committing to implementation:

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.

Advanced Configuration

Require Plan Approval for Risky Tasks

For complex or risky work, require teammates to plan before implementing:

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

The teammate works in read-only plan mode until the lead approves. If rejected, they revise and resubmit. You can influence approval criteria:

"Only approve plans that include test coverage"
"Reject plans that modify the database schema"

Delegate Mode

Sometimes the lead starts implementing instead of coordinating. Press Shift+Tab to restrict the lead to coordination-only tools—spawning, messaging, shutting down teammates, and managing tasks. No code touching.

Direct Teammate Communication

Each teammate is a full Claude Code session. Message any teammate directly without going through the lead:

In-process mode: Shift+Up/Down to select, then type your message
Split-pane mode: Click into the teammate's pane and interact directly

Task Dependencies

Tasks can depend on other tasks. Pending tasks with unresolved dependencies cannot be claimed until those dependencies complete. The system handles unblocking automatically.

Best Practices

1. Give Teammates Enough Context

Teammates load project context automatically (CLAUDE.md, MCP servers, skills) but don't inherit the lead's conversation history. Include task-specific details in spawn prompts:

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

2. Size Tasks Appropriately

Task SizeProblemToo SmallCoordination overhead exceeds the benefitToo LargeTeammates work too long without check-ins, risking wasted effortJust RightSelf-contained units producing clear deliverables (a function, test file, or review)

Aim for 5-6 tasks per teammate to keep everyone productive and allow reassignment if someone gets stuck.

3. Avoid File Conflicts

Two teammates editing the same file leads to overwrites. Structure work so each teammate owns different files. If they must touch the same file, sequence the tasks with dependencies.

4. Start with Read-Only Tasks

If you're new to agent teams, start with code reviews or research—tasks with clear boundaries that don't require writing code. Learn coordination patterns before parallelized implementation.

5. Monitor and Steer

Check in on teammates' progress regularly. Redirect approaches that aren't working. Letting a team run unattended too long increases wasted effort.

When NOT to Use Agent Teams

Agent teams add coordination overhead and use significantly more tokens (~5x) than a single session. They're not always the right choice:

Sequential tasks: Work that must happen in order doesn't benefit from parallelization
Same-file edits: Multiple agents editing one file causes conflicts
Highly dependent work: Tasks with many interdependencies create blocking chains
Simple fixes: A typo fix doesn't need a team
Routine tasks: Single sessions are more cost-effective for everyday work

The sweet spot is complex work where parallel exploration adds real value and teammates can operate largely independently.

Troubleshooting Common Issues

Agent Teams Option Doesn't Appear

The environment flag isn't set correctly. Verify with:

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Should output 1. If using settings.json, ensure the flag is in the env block, not at root level.

Teammates Not Appearing

In in-process mode, teammates may already be running. Press Shift+Down to cycle through active teammates
Check if your task warranted a team—Claude decides based on complexity
For split panes, verify tmux is installed: which tmux

Teammate Seems Stuck

Task status can lag. The lead might think a task is pending when the teammate already started. Give it 10-15 seconds. If truly stuck, message the teammate directly through the lead.

Split Panes Not Working

Split-pane mode requires tmux or iTerm2. It does NOT work in:

VS Code integrated terminal
Windows Terminal
Ghostty

Use --teammate-mode in-process instead.

Lead Shuts Down Before Work Is Done

The lead may decide the team is finished prematurely. Tell it to keep going or wait for teammates:

Wait for your teammates to complete their tasks before proceeding

Cannot Resume Session with Teammates

Known limitation: /resume and /rewind don't restore in-process teammates. The lead may try to message teammates that no longer exist. Start a fresh session and spawn new teammates.

Orphaned tmux Sessions

If a tmux session persists after the team ends:

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

Current Limitations

Agent teams are experimental. Be aware of these limitations:

No session resumption: /resume and /rewind don't restore teammates
One team per session: Clean up before starting a new team
No nested teams: Teammates cannot spawn their own teams
Lead is fixed: Can't promote a teammate to lead or transfer leadership
Permissions propagate: All teammates inherit the lead's permissions at spawn
Shutdown can be slow: Teammates finish current work before exiting

Storage Locations

Teams and tasks are stored locally:

~/.claude/teams/{team-name}/config.json  # Team metadata + members
~/.claude/tasks/{team-name}/              # Task list

Teammates can read the config file to discover other team members.

Conclusion

Claude Code agent teams represent a powerful evolution in AI-assisted development. For the right use cases—parallel code reviews, adversarial debugging, multi-module features—the parallel exploration finds things a single agent misses. The competing hypotheses pattern alone justifies learning this feature.

Start with read-only tasks like code reviews. Learn the coordination patterns. Then scale to parallel implementation as you get comfortable. The token cost is real (~5x per teammate), so reserve agent teams for work that genuinely benefits from multiple perspectives working in parallel.

For simpler tasks, stick with subagents or single sessions. Match your tools to the problem—not the other way around.

For more AI coding tutorials and automation guides, explore our other articles on making the most of modern AI development tools, including our popular Claude Code tips and tricks and API pricing guide.