What Are Agent Teams?

Agent Teams is an experimental feature in Claude Code that lets you coordinate multiple Claude Code instances working together. Think of it as having a development team where one session acts as the team lead, coordinating work, assigning tasks, and synthesizing results, while teammates work independently in their own context windows.

This differs fundamentally from subagents (which run within a single session and only report back to the main agent). With Agent Teams, you can interact with individual teammates directly without going through the lead.

---

When Should You Use Agent Teams?

Agent Teams shine in scenarios where parallel exploration adds real value:

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: Each teammate can own a separate piece of the codebase without stepping on each other’s toes.

Debugging with Competing Hypotheses: Test different theories in parallel and converge on the answer faster.

Cross-Layer Coordination: Changes spanning frontend, backend, and tests can each be owned by a different teammate.

When NOT to Use Agent Teams

Agent teams add coordination overhead and consume significantly more tokens than a single session. They’re not ideal for:

• Sequential tasks with many dependencies
• Same-file edits requiring tight coordination
• Simple tasks that don’t benefit from parallelization

For these scenarios, stick with a single session or use subagents instead.

---

Agent Teams vs Subagents: Quick Comparison

Aspect	Subagents	Agent Teams
Context	Own context window; results return to caller	Own context window; fully independent
Communication	Report results back to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best For	Focused tasks where only the result matters	Complex work requiring discussion and collaboration
Token Cost	Lower: results summarized back	Higher: each teammate is a separate Claude instance

---

Getting Started

Enable Agent Teams

Agent Teams are disabled by default. Enable them by adding this to your settings.json:

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

Start Your First Team

Simply describe the task and team structure you want in natural language:

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 the team, spawns teammates, and coordinates work based on your prompt.

---

Display Modes

Agent Teams support two display modes:

In-process Mode: All teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them directly. Works in any terminal.

Split Panes Mode: Each teammate gets its own pane. See everyone’s output at once and click into a pane to interact directly. Requires tmux or iTerm2.

Configure in settings.json:

{
  "teammateMode": "in-process"
}

Or pass as a flag:

claude --teammate-mode in-process

---

Key Features

Specify Teammates and Models

You have full control over team composition:

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

Require Plan Approval

For complex or risky tasks, 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 their approach.

Delegate Mode

Prevent the lead from implementing tasks itself by pressing Shift+Tab to cycle into delegate mode. This restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.

Talk to Teammates Directly

Each teammate is a full, independent Claude Code session. Message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

---

How It Works Under the Hood

An agent team consists of:

Component	Role
Team Lead	The main Claude Code session that creates the team, spawns teammates, and coordinates work
Teammates	Separate Claude Code instances that each work on assigned tasks
Task List	Shared list of work items that teammates claim and complete
Mailbox	Messaging system for communication between agents

Teams and tasks are stored locally:

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

---

Real-World Use Cases

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 applies a different filter. The lead synthesizes findings across all three.

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 ensures the theory that survives is more likely to be the actual root cause.

---

Best Practices

Give teammates enough context: Include task-specific details in the spawn prompt since they don’t inherit the lead’s conversation history.

Size tasks appropriately: Not too small (coordination overhead exceeds benefit), not too large (teammates work too long without check-ins). Aim for self-contained units that produce clear deliverables.

Avoid file conflicts: Two teammates editing the same file leads to overwrites. Break work so each teammate owns different files.

Monitor and steer: Check in on progress, redirect approaches that aren’t working, and synthesize findings as they come in.

---

Current Limitations

As an experimental feature, Agent Teams have known limitations:

• No session resumption with in-process teammates
• Task status can lag if teammates fail to mark tasks completed
• Shutdown can be slow (teammates finish current request first)
• One team per session
• No nested teams (teammates cannot spawn their own teams)
• Lead is fixed for the team’s lifetime
• Split panes require tmux or iTerm2 (not supported in VS Code terminal, Windows Terminal, or Ghostty)

---

Conclusion

Agent Teams represent an exciting evolution in AI-assisted development. By coordinating multiple Claude instances with shared tasks and inter-agent communication, complex software engineering workflows become more manageable.

While still experimental, this feature is worth exploring for research-heavy tasks, parallel reviews, and debugging sessions where multiple perspectives add value. Start with tasks that have clear boundaries and don’t require writing code to get a feel for the coordination dynamics before tackling more complex implementations.

For more details, check the official documentation.