Agent teams are Claude Code's most powerful new feature. Instead of one AI working sequentially, you can orchestrate multiple Claude instances working in parallel—each with its own context, each communicating directly with teammates.

This guide covers everything: when to use agent teams, how to set them up, and best practices for parallel AI development.

What Are Agent Teams?

Agent teams let you coordinate multiple Claude Code sessions working together:

Team Lead — Coordinates work, assigns tasks, synthesizes results
Teammates — Work independently in their own context windows
Direct Communication — Teammates message each other directly

Think of it like having a team of senior engineers, each owning a piece of the architecture, coordinating autonomously.

Agent Teams vs Subagents

Both parallelize work, but they operate differently:

Feature	Subagents	Agent Teams
Context	Results return to caller	Fully independent
Communication	Report to main agent only	Message each other
Coordination	Main agent manages all	Self-coordination
Best For	Focused tasks	Complex collaboration
Token Cost	Lower	Higher

Rule of thumb: Use subagents for quick, focused tasks. Use agent teams when teammates need to discuss, challenge each other, and coordinate.

Best Use Cases

Agent teams shine when parallel exploration adds value:

1. Research and Review

Multiple teammates investigate different aspects simultaneously, then share and challenge findings.

2. New Modules or Features

Each teammate owns a separate piece without stepping on each other.

3. Debugging Competing Hypotheses

Teammates test different theories in parallel and converge faster.

4. Cross-Layer Coordination

Changes spanning frontend, backend, and tests—each owned by a different teammate.

When NOT to Use Agent Teams

Sequential tasks — One thing depends on another
Same-file edits — Teammates will conflict
Tight dependencies — Too much coordination overhead

For these, stick with a single session or subagents.

Enable Agent Teams

Agent teams are disabled by default. Enable in settings.json:

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

Start Your First Team

Tell Claude to create a team in natural language:

I'm designing a CLI tool that helps developers track TODO comments.
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, coordinates work, and synthesizes findings.

Display Modes

In-Process (Default)

All teammates run in your main terminal. Use Shift+Up/Down to select and message them.

Split Panes

Each teammate gets its own pane. See everyone's output at once. Requires tmux or iTerm2.

Configure in settings:

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

Control Your Team

Specify Team Size

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

Require Plan Approval

For risky tasks, require teammates to plan before implementing:

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

The lead reviews and approves/rejects plans before work begins.

Delegate Mode

Prevent the lead from implementing—restrict to coordination only:

Start a team
Press Shift+Tab to enable delegate mode
Lead only spawns, messages, and manages tasks

Example: Building a Feature

Build a user authentication system with agent teams:
- Backend teammate: API routes and database schema
- Frontend teammate: Login/signup UI components
- Security teammate: Input validation and encryption
- Test teammate: Unit and integration tests

Coordinate through a shared task list. Each teammate owns their domain.

Best Practices

1. Clear Domain Boundaries

Give each teammate a distinct area. Overlap causes conflicts.

2. Start Small

2-3 teammates is usually enough. More adds coordination overhead.

3. Use Shared Task Lists

Teammates see and coordinate through a shared task list automatically.

4. Let Them Challenge Each Other

The power of teams is discussion. Let teammates disagree and synthesize.

5. Clean Up

Teams use significant tokens. Shut down when done.

Token Considerations

Agent teams are expensive:

Each teammate is a separate Claude instance
Communication multiplies token usage
Use for complex tasks where parallel value justifies cost

For cost-sensitive work, consider Serenities AI—use your AI subscriptions instead of per-token API pricing.

Conclusion

Agent teams transform Claude Code from a single assistant into a coordinated AI development team. Use them for complex, parallelizable work where discussion and collaboration add value.

The future of coding isn't one AI helping you—it's a team of AIs working alongside you.

Start with a simple team, learn the patterns, then scale up.

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