← Back to all guides

Agent Teams

Introduction

So far in this series we’ve covered individual Claude Code sessions — one instance, one conversation. Agent teams take this further by letting you coordinate multiple Claude Code instances working together in parallel, each with its own context window, communicating with each other and sharing a task list.

For the full official documentation, see the Agent Teams docs.

If you haven’t read the earlier guides: Installing Claude Code, Using the Claude Code TUI, CLAUDE.md and Settings, Skills, Agents, and MCP Servers, Hooks, Plugins and Marketplaces.

Enabling Agent Teams

Agent teams are experimental and disabled by default. Enable them by adding the environment variable to your settings.json:

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

Or export it in your shell before starting Claude Code:

Teams vs Sub-Agents

Before diving in, it’s worth understanding how teams differ from the sub-agents we covered in the skills and agents guide:

Use sub-agents 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.

How Teams Work

An agent team consists of four components:

• Team lead — Your main Claude Code session. It creates the team, spawns teammates, and coordinates work.
• Teammates — Separate Claude Code instances that each work on assigned tasks independently.
• Task list — A shared list of work items that teammates claim and complete. Stored at ~/.claude/tasks/{team-name}/.
• Mailbox — A messaging system for direct communication between agents.

The team lead assigns tasks, and teammates either receive assignments or self-claim from the shared task list. Task claiming uses file locking to prevent race conditions. Tasks can have dependencies — a task with unresolved dependencies won’t be claimed until those dependencies complete.

Starting a Team

Tell Claude to create a team and describe what you want. Claude decides how many teammates to spawn based on your task:

I'm refactoring the authentication module. Create an agent team:
- One teammate to update the auth middleware
- One teammate to rewrite the tests
- One teammate to update the API documentation

You can also specify models for teammates:

Create a team with 4 teammates to review this PR.
Use Sonnet for each teammate.

Claude creates the team, spawns the teammates, distributes the work, and coordinates results.

Display Modes

Agent teams support two display modes:

In-Process (Default)

All teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal.

Split Panes

Each teammate gets its own terminal pane. You can see everyone’s output at once and click into a pane to interact directly. Requires tmux or iTerm2.

Configure the display mode in settings:

{
  "teammateMode": "in-process"
}

Or per-session:

The default is "auto" — split panes if you’re already in a tmux session, in-process otherwise.

Working with Teams

Talking to Teammates Directly

Each teammate is a full, independent Claude Code session. You can message any teammate directly:

• In-process mode — Shift+Down to cycle through teammates, then type your message. Press Ctrl+T to toggle the task list.
• Split-pane mode — Click into a teammate’s pane to interact with their session.

Task Assignment

The lead creates and assigns tasks. There are two patterns:

• Lead assigns — Tell the lead which task to give to which teammate.
• Self-claim — After finishing a task, a teammate picks up the next unassigned, unblocked task automatically.

Plan Approval

For risky or complex tasks, you can require teammates to plan before implementing:

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

The teammate works in read-only plan mode until the lead approves their approach. If rejected, they revise and resubmit.

Shutting Down

Ask the lead to shut down individual teammates or clean up the whole team:

Ask the researcher teammate to shut down

When you’re done with the entire team:

Clean up the team

When to Use Teams

Agent teams shine when parallel exploration adds real value. The best use cases are:

Research and review — Multiple teammates investigate different aspects of a problem simultaneously, then share and challenge each other’s findings.

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.

New modules or features — Teammates each own a separate piece without stepping on each other’s files.

Debugging with competing hypotheses — Teammates test different theories in parallel and converge on the answer faster. This is particularly powerful because a single agent tends to anchor on the first plausible explanation and stop looking.

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.

Cross-layer coordination — Changes that span frontend, backend, and tests, each owned by a different teammate.

Best Practices

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 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 tokens stored in
httpOnly cookies."

Choose the Right Team Size

Start with 3-5 teammates for most workflows. Token costs scale linearly — each teammate has its own context window. Aim for 5-6 tasks per teammate to keep everyone productive without excessive context switching.

Three focused teammates often outperform five scattered ones.

Avoid File Conflicts

Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files. This is the most common source of problems with agent teams.

Monitor and Steer

Check in on progress, redirect approaches that aren’t working, and don’t let teams run unattended for too long. The lead coordinates autonomously, but your oversight prevents wasted effort.

Enforcing Quality with Hooks

Two hook events are specifically designed for agent teams:

• TeammateIdle — Fires when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.
• TaskCompleted — Fires when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

These let you enforce quality gates — for example, requiring that all tests pass before a task can be marked as done.

Token Usage

Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and usage scales with the number of active teammates. For research, review, and feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective.

Limitations

Agent teams are experimental. Current limitations:

• No session resumption — /resume and /rewind don’t restore in-process teammates. After resuming, the lead may try to message teammates that no longer exist.
• Task status can lag — Teammates sometimes fail to mark tasks as completed, blocking dependent tasks.
• One team per session — A lead can only manage one team at a time.
• No nested teams — Teammates cannot spawn their own teams.
• Lead is fixed — The session that creates the team is the lead for its lifetime.
• Permissions set at spawn — All teammates start with the lead’s permission mode.
• Split panes require tmux or iTerm2 — In-process mode works in any terminal, but split panes aren’t supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

Wrapping Up

Agent teams are the most powerful coordination mechanism in Claude Code — multiple independent instances working in parallel, communicating directly, and sharing a task list. They’re also the most token-intensive, so use them when the work genuinely benefits from parallel exploration.

Start with research and review tasks to get a feel for how teams coordinate before moving to parallel implementation work. And always break work so teammates own separate files — that’s the single most important rule for avoiding conflicts.

If you missed the earlier guides in this series:

1. Installing Claude Code
2. Using the Claude Code TUI
3. CLAUDE.md and Settings
4. Skills, Agents, and MCP Servers
5. Hooks
6. Plugins and Marketplaces
7. Agent Teams (you are here)