Claude Code Agent Teams

Problem: A gnarly refactor spans the API, database migrations, test coverage, and docs. One Claude Code session chews through the work linearly. Subagents can fan out, but they only talk to the main agent. They don't swap notes, push back on each other, or coordinate directly. The moment your AI workers need to actually collaborate, subagents run out of rope.

Quick Win: Flip on Agent Teams and describe the crew you want in a single 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.

A team lead spins up, three teammates drop into their own scopes, and they share a task list plus a mailbox. Each owns its lane. No collisions. No silence.

Note on terminology: The feature here is Claude Code's built-in Agent Teams, an experimental system shipped by Anthropic. If you want a do-it-yourself builder-validator setup using the Task tool, that lives in team orchestration with builder-validator chains. Both get you to multi-agent work. Under the hood they behave nothing alike.

That distinction is the whole point of this page. If one main agent can coordinate specialists and collect their answers, start with Agent Fundamentals and Agent Patterns. Read this page when the teammates themselves need to talk, challenge each other, and coordinate without routing every message back through one parent thread.

What Agent Teams Actually Is

Agent Teams is an experimental mode that runs several Claude Code sessions on the same project, together. One session becomes the lead. The lead hands out tasks, keeps the work aligned, and rolls up the results. Every other teammate runs in its own context window and can message any other teammate directly.

Where this breaks from subagents is the wire. A subagent lives inside one parent session and can only send its answer back to that parent. Mid-task discoveries stay trapped. Coordination between two subagents always routes through the main agent. Agent Teams kills that hop. Teammates DM each other, pull tasks off a shared list, and debate problems in real time. You can jump into any teammate's session yourself without asking the lead for permission.

A useful picture: subagents are freelancers you text separate jobs to. An Agent Team is a squad in the same room, each on their piece, staying in sync by talking. It's the gap between a gig queue and an actual crew.

Why This Matters Now

Anthropic rolled Agent Teams out as experimental alongside the Opus 4.6 release, and it marks a real step forward for agentic work. Independent developers had been stitching similar setups together for months using projects like OpenClaw and hand-rolled orchestration scripts. Claude Code now has the pattern baked in.

Three reasons this lands:

1. Built-in beats bolted-on. Shared task lists, the mailbox, and the teammate lifecycle are part of Claude Code itself. Nothing external. Nothing brittle.

2. Multi-agent is growing up. Developers who build reps with agent teams right now will ride a serious edge as the tooling keeps evolving. The spread between "uses Claude Code" and "runs Claude Code teams" is about to get wide.

3. Complex projects need talking, not just forking. Splitting tasks up gets you parallel work. Agent Teams gets you parallel work plus live coordination, where teammates trade context, challenge calls, and land on stronger answers together.

When to Reach for Agent Teams

Running a team costs real tokens and adds coordination overhead on top of a single session. The fit is strongest when each teammate can own a distinct slice of work but still benefits from the group chat.

Strong Use Cases

• Research and review: Different teammates dig into different angles of a problem, then compare notes and poke holes in each other's findings
• New modules or features: Each teammate takes one component with no file overlap
• Debugging with competing hypotheses: Each teammate tests a different theory in parallel and actively tries to disprove the others
• Cross-layer coordination: A change that crosses frontend, backend, and tests, with one teammate per layer
• Debate and consensus: Several teammates argue opposing positions on an architectural call and converge on the strongest one
• Large-scale inventory or classification: Teammates split a big dataset and grind through their slices independently

For prompt templates and 10+ worked scenarios covering marketing, research, and non-dev jobs, see Agent Teams Use Cases and Prompt Templates.

When Teams Are Worth The Cost

Agent Teams are not just "more agents." They are a coordination layer, and that layer is only worth paying for when collaboration itself changes the result.

Teams are usually worth it when:

• each teammate can own a distinct lane
• discoveries in one lane will change what another teammate should do
• comparing viewpoints is part of the job
• the work would be meaningfully slower or weaker if routed through one main thread only

Teams are usually not worth it when:

• one agent could finish the job cleanly
• the work is mostly sequential
• everyone would be editing the same files
• you only need several independent outputs and a summary

That last case is where subagents still win. If workers do not need to talk, do not pay for a system built around talking.

When to Skip It

Sequential work, same-file edits, or anything with tight dependencies: a single session or a subagent pattern costs less and runs cleaner. If the workers don't need to talk, the coordination layer is pure tax. For parallel edits that are genuinely independent, /batch is simpler and handles worktree isolation for you. Async workflows cover basic parallel runs without the collaboration layer on top. For common traps and how to dodge them, see our agent teams best practices.

Subagents vs Agent Teams: Picking the Right Tool

Both parallelize work. They operate at different layers. The question that decides it: do your workers actually need to talk to each other?

Subagents fit when you need fast, narrow workers that hand back a result. Teams fit when those workers need to share context, push back on each other, and run their own coordination. On big projects, layer both: plan first to set roles and boundaries, then run a team for execution.

On how subagents get routed in the first place, see sub-agent best practices.

Step-by-Step: Your First Team

In real use, teammates spawn in 20 to 30 seconds and start producing results inside the first minute. A 3-teammate run burns roughly 3 to 4 times the tokens of a single session doing the same work in sequence. On complex tasks the time savings pay for that easily.

Step 1: Turn It On

Set the environment variable in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or drop it into your settings.json so it sticks across sessions:

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

Step 2: Describe the Job and the Team

Use plain English. Be specific about who does what:

Create an agent team to review our authentication system. Spawn three teammates:
- Security reviewer: audit for vulnerabilities, check token handling
- Performance analyst: profile response times, identify bottlenecks
- Test coverage checker: verify edge cases, find untested paths
Have them share findings and coordinate through the task list.

What To Put In The Team Brief

The first team prompt matters more than most people think. A vague brief creates vague collaboration.

A strong team brief includes:

• the overall goal
• the teammate roles
• file or system boundaries
• what teammates should coordinate on
• what counts as done

Example:

Create an agent team to ship the billing refactor.

Team:
- API teammate: own route handlers and webhook flow
- Data teammate: own schema, migrations, and backfills
- Test teammate: own integration coverage and failure cases

Coordination points:
- align on the event model before code changes
- flag any contract mismatch immediately
- do not edit the same file without discussing it first

Done means:
- migrations apply cleanly
- webhook flow still passes
- billing test suite is green

That prompt gives the team roles, boundaries, communication points, and a finish line. Without that, "coordinate" usually just means "talk a lot."

Step 3: Watch the Team Form, Steer When Needed

Claude turns your session into the lead, spawns the teammates, and drops tasks onto the shared list. Claude can also suggest a team on its own if it thinks your request fits. Either way, the wheel is still yours.

Use keyboard shortcuts to watch and steer: Shift+Up/Down to pick a teammate, Ctrl+T for the task list, Enter to drop into a session, Escape to interrupt.

Step 4: Clean Up

Once the work lands, wind the team down:

Ask all teammates to shut down, then clean up the team.

Always run cleanup through the lead. Teammates go down first because the lead won't clean up while any teammate is still alive.

For the deep cut on display modes, delegate mode, plan approval, hooks, task assignment, and token costs, see Agent Teams Advanced Controls.

Architecture: How the Pieces Fit

Four components make up a team:

The team and its config sit on disk locally:

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

Every teammate gets its own context window. At spawn time, a teammate loads the same project context any normal Claude Code session would: your CLAUDE.md, MCP servers, and skills. It also reads the spawn prompt from the lead. What it does not inherit is the lead's conversation history.

Communication rides on automatic message delivery, idle notifications, the shared task list, direct messages (one teammate only), and broadcasts (everyone at once, used carefully because cost scales with team size).

Teammates inherit the lead's permission settings at spawn. You can change a specific teammate's mode after spawning, not at spawn time.

For getting more out of CLAUDE.md in a team setup, steering team behavior, and keeping token costs sane, see Agent Teams Advanced Controls.

Dive Deeper

This is the hub page. Three companion guides go further on specific pieces:

• Advanced Controls: Display modes, delegate mode, plan approval, quality gate hooks, task assignment, token cost management, and optimizing CLAUDE.md for teams
• Use Cases and Prompt Templates: 10+ real-world scenarios with copy-paste prompts for code review, debugging, full-stack features, architecture decisions, marketing campaigns, and a progressive getting-started path
• Best Practices and Troubleshooting: Battle-tested practices, plan mode behavior, troubleshooting guide, current limitations, and recent fixes from v2.1.33 through v2.1.45
• End-to-End Workflow: The complete 7-step pipeline from brain dump to production: planning, contract chains, wave execution, and post-build validation

If you want interactive work to feel even snappier while a team is running, check out Fast Mode for 2.5x speed on Opus 4.6 responses.

Coordination at Scale

As your teams get bigger, the hard question flips from "can I parallelize this?" to "how do I actually manage the orchestration?" Three patterns carry weight at scale:

1. Reusable spawn prompt templates. Keep a small library of prompt shapes for your most common lineups (review team, build team, research team). Each one defines roles, file boundaries, and done criteria so nothing gets rebuilt every session. For the workflow those templates plug into, see the end-to-end workflow guide.

2. Permission presets. Pre-approve your most common operations in permission settings before you spawn the team. Otherwise a fresh team drowns in approval prompts for the first ten minutes.

3. CLAUDE.md as shared runtime context. A tight CLAUDE.md with module boundaries, verification commands, and operational context slashes the per-teammate exploration cost. Three teammates reading one clear CLAUDE.md is far cheaper than three teammates independently roaming the codebase.

The Multi-Agent Spectrum

Agent Teams sits on one end of a range of multi-agent patterns inside Claude Code. Knowing where each one lands helps you pick:

Mix and match by need. Run a team for the collaborative exploration phase, then swap to builder-validator pairs when you hit implementation and need hard quality gates. Long-running team sessions live and die by the same context strategies any multi-agent workflow uses.

Reps with agent teams right now compound as multi-agent tooling grows up. Start with a review task this week. The cost is small, and the way you think about complex work will shift once you see teammates actually coordinate.