If you've used Claude Code for a while, you've probably seen subagents—specialized AI workers that Claude can use for research, code exploration, reviews, or other focused tasks.
Agent Teams are a step further.
Instead of relying on one Claude Code session to handle a large task, Agent Teams let multiple Claude Code instances work as a coordinated group. One session acts as the team lead, while other Claude Code sessions become teammates with their own context windows. They can work in parallel, communicate with each other, and coordinate tasks.
This can be useful for complex software projects where several independent parts need to be investigated, reviewed, or implemented at the same time.
In this beginner guide, you'll learn what Claude Code Agent Teams are, how they work, how they differ from subagents, how to enable them, when to use them, and what limitations you should know before using them.
Important: Agent Teams are currently an experimental Claude Code feature and are disabled by default.
What Are Claude Code Agent Teams?
Claude Code Agent Teams let you coordinate multiple independent Claude Code sessions around one larger task.
A typical team contains:
- Team lead — the main Claude Code session that plans and coordinates the work.
- Teammates — separate Claude Code instances that work on assigned tasks.
- Task list — a shared list of work that can be pending, in progress, or completed.
- Messaging system — allows agents to communicate and exchange information.
Each teammate has its own context window. This means one teammate doesn't have to consume the lead's entire conversation history to work on its assigned task.
The lead can divide a large problem into smaller pieces and ask different teammates to investigate them simultaneously.
For example, imagine you're reviewing a large application.
You could ask Claude to create:
- one teammate for security,
- one for performance,
- one for test coverage,
- and one for architecture.
Each teammate can investigate its own area while communicating findings back to the team.
Anthropic's documentation specifically lists parallel research and review, independent modules, competing debugging hypotheses, and cross-layer changes as strong use cases for Agent Teams.
How Claude Code Agent Teams Work
Think of Agent Teams as a small AI development team.
The basic workflow looks like this:
You → Team Lead → Teammates → Shared Tasks + Messages → Final Result
The team lead receives your overall objective and decides how to divide the work.
The teammates then work independently.
1. Team Lead
The lead is the Claude Code session you initially interact with.
It can:
- create teammates,
- assign work,
- coordinate tasks,
- communicate with teammates,
- monitor progress,
- and synthesize the final results.
2. Teammates
Every teammate is a separate Claude Code instance with its own context window.
Teammates can:
- inspect files,
- run commands,
- investigate problems,
- write code,
- perform reviews,
- communicate with other teammates,
- and report their findings.
You can also communicate directly with an individual teammate instead of always going through the lead.
3. Shared Task List
The team can use a shared task list to coordinate work.
Tasks can have three states:
- Pending
- In progress
- Completed
Tasks can also have dependencies. For example, a testing task can wait until the implementation task is completed.
Claude Code uses task locking when teammates claim tasks, helping prevent multiple agents from claiming the same task simultaneously.
4. Agent Messaging
Teammates can communicate directly.
For example:
"The authentication module uses JWT cookies. Please check whether your frontend changes affect the login flow."
That type of peer-to-peer communication is one of the important differences between a coordinated Agent Team and simply running several unrelated Claude Code sessions.
Current Claude Code documentation also notes that named subagents can communicate with each other, so the old explanation that all subagents can only report to their parent is too simplistic.
Agent Teams vs Subagents
This is one of the most important concepts for beginners.
Both features let Claude delegate work, but they are designed for different workflows.
| Feature | Subagents | Agent Teams |
|---|---|---|
| Context | Separate context | Separate context for each teammate |
| Main purpose | Focused delegated tasks | Coordinated multi-agent work |
| Coordination | Usually centered around the parent session | Team lead + teammates |
| Communication | Can return results; named agents can communicate | Direct teammate communication |
| Task coordination | Depends on subagent workflow | Shared task list can coordinate work |
| Best for | Research, focused checks, isolated tasks | Complex parallel work |
| Token usage | Usually lower | Higher |
| Complexity | Lower | Higher |
Claude's current documentation recommends subagents when you need focused workers that return useful results, while Agent Teams make more sense when agents need to share findings, challenge each other, and coordinate independently.
Simple Example
Imagine you ask Claude:
"Research three authentication libraries and tell me which features they support."
A subagent may be enough.
But if you're asking:
"Review this application from security, performance, architecture, and testing perspectives and have the agents challenge each other's findings."
An Agent Team can make more sense because multiple independent workstreams can run simultaneously.
Agent Teams vs Running Multiple Claude Code Sessions
You can also open several terminal windows and run Claude Code manually.
So why use Agent Teams?
With independent sessions, you are responsible for coordinating the work.
You have to:
- decide what each session should do,
- move information between sessions,
- track progress,
- combine results,
- and resolve dependencies yourself.
Agent Teams provide a coordination layer around those sessions.
The lead can organize tasks, teammates can communicate, and the task system can track work.
Anthropic's own advanced-pattern material describes Agent Teams as useful for splitting large tasks into independent workstreams that need coordination, while ordinary parallel Claude sessions are useful when unrelated tasks can simply be worked on independently.
How to Enable Claude Code Agent Teams
Agent Teams are disabled by default.
To enable them, add the following environment variable to your Claude Code settings:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Claude Code's current documentation confirms this is the setting used to enable Agent Teams.
You can configure it in your settings.json or set the environment variable in your shell.
Once enabled, Claude can spawn teammates when the task requires them.
Important: Agent Teams Require an Interactive Session
Agent Teams are intended for interactive Claude Code sessions.
In non-interactive mode using -p, including Agent SDK sessions, Claude does not spawn teammates as Agent Teams. A named subagent in that situation runs as an ordinary subagent instead.
How to Start Your First Agent Team
Once Agent Teams are enabled, you don't need complicated commands.
You can describe the team you want using natural language.
For example:
I'm building a CLI tool for tracking TODO comments. Create three teammates: 1. One for UX and CLI design 2. One for technical architecture 3. One to challenge the proposed design and find weaknesses Have them work independently and then summarize the findings.
Claude can create the teammates, divide the work, and synthesize the results.
The current documentation specifically uses a similar pattern: separate teammates explore UX, technical architecture, and a devil's-advocate perspective.
Ask Explicitly for a Team
Sometimes Claude may choose an ordinary subagent instead of creating a full team.
If you specifically want Agent Teams, say so:
"Create an Agent Team with three teammates."
This makes your intent clearer.
What Context Do Teammates Receive?
This is an important detail beginners often miss.
A teammate gets the project's relevant context, including things such as:
- CLAUDE.md
- MCP servers
- skills
- its own spawn instructions
But it does not automatically inherit the lead's conversation history.
So if you discussed an important architectural decision with the lead earlier, don't assume every teammate knows about it.
Instead, include important information in the teammate's instructions.
For example:
Review src/auth/ for security problems. The application uses JWT tokens stored in httpOnly cookies. Focus on authentication, session handling, and input validation.
Specific prompts reduce the chance that a teammate spends time investigating the wrong thing.
When Should You Use Agent Teams?
Agent Teams are most useful when the work can genuinely happen in parallel.
1. Parallel Code Reviews
You can assign different review dimensions to different teammates.
For example:
- Security
- Performance
- Test coverage
- Architecture
Each teammate investigates a different concern and the lead combines the findings.
Anthropic's documentation gives parallel code review as one of its example Agent Team workflows.
2. Debugging With Competing Hypotheses
Suppose your application crashes after a user logs in, but you don't know why.
Instead of having one agent follow one theory, you can ask several teammates to investigate different possible causes.
One might investigate:
- authentication,
- another database connections,
- another frontend state,
- another API errors,
- another deployment configuration.
They can challenge each other's hypotheses before the lead synthesizes the results.
This approach is specifically documented as a useful Agent Team pattern.
3. Building Separate Modules
Agent Teams can work well when different teammates own different modules.
For example:
- Frontend teammate
- Backend teammate
- Database teammate
- Testing teammate
The key is to define clear ownership.
4. Cross-Layer Changes
Large changes sometimes affect multiple parts of an application.
For example:
Frontend → API → Database → Tests
If those areas can be divided cleanly, multiple teammates can investigate or implement their parts in parallel.
When Agent Teams Are a Bad Idea
More agents do not automatically mean faster development.
Agent Teams can be inefficient when the work is:
- very small,
- highly sequential,
- dependent on the previous step,
- concentrated in the same file,
- or easy for one Claude Code session to handle.
Anthropic explicitly warns that Agent Teams add coordination overhead and use significantly more tokens. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagent can be more appropriate.
Avoid Multiple Agents Editing the Same File
This is particularly important.
If two teammates modify the same file at the same time, their changes can conflict or overwrite each other.
Instead, divide ownership:
Bad:
Agent 1 → app.js
Agent 2 → app.js
Better:
Agent 1 → frontend module
Agent 2 → backend module
Agent 3 → tests
The official documentation recommends avoiding file conflicts by giving teammates separate ownership.
How Much Do Agent Teams Cost?
Agent Teams generally use more tokens than a single Claude Code session because every teammate has its own context and runs independently.
As the number of active teammates increases, token usage increases as well.
That means you shouldn't create a team simply because you can.
For a simple task like:
"Rename this function."
One Claude Code session is enough.
For:
"Review this large application from five independent perspectives."
Parallel agents may provide more value.
Start With 3–5 Teammates
Claude Code's current documentation recommends starting with 3–5 teammates for most workflows.
There is no hard universal team-size rule, but coordination overhead and token usage increase as the team grows, while additional teammates eventually provide diminishing returns.
A team of three focused agents can therefore be more useful than a team of ten poorly defined agents.
Choosing the Right Model for Teammates
You can also specify which model teammates should use.
For example:
Spawn 4 teammates to review these modules. Use Sonnet for each teammate.
Claude Code can select a teammate's model based on your prompt, its subagent definition, environment configuration, or the lead's current model, depending on the configuration.
This gives advanced users another way to balance capability and usage.
In-Process vs Split-Pane Mode
Claude Code currently supports two main ways of displaying teammates.
In-Process Mode
This is the default.
All teammates run within the main terminal experience, and you can select a teammate from the agent panel.
This mode doesn't require additional terminal software.
Split-Pane Mode
Each teammate gets its own terminal pane.
This can make it easier to watch several agents simultaneously.
Split-pane mode requires tmux or iTerm2, depending on your setup.
For beginners, in-process mode is usually simpler because it avoids extra terminal configuration.
Best Practices for Claude Code Agent Teams
1. Give Every Teammate Enough Context
Don't assume teammates know what the lead discussed earlier.
Include:
- relevant files,
- technical constraints,
- expected output,
- acceptance criteria,
- and important architecture decisions.
2. Give Each Teammate Clear Ownership
Avoid overlapping file ownership.
Instead of:
"Everyone improve the application."
Use:
"You own the API layer."
"You own the frontend components."
"You own the integration tests."
3. Start With Research and Review
If you're new to Agent Teams, don't immediately give five agents a huge coding task.
Start with:
- code review,
- library research,
- bug investigation,
- architecture analysis.
These workflows let you see the benefits of parallel exploration without immediately dealing with complex code conflicts.
4. Make Tasks Self-Contained
A good task should have:
- a clear objective,
- clear ownership,
- a defined output,
- and minimal dependencies.
Tasks that are too small waste coordination time.
Tasks that are too large can allow a teammate to spend a long time going in the wrong direction before anyone notices.
5. Monitor the Team
Don't assume that a team can always be left completely unattended.
Check progress, redirect agents when necessary, and review their output.
The official documentation specifically recommends monitoring and steering teammates rather than allowing a team to run unattended for too long.
Important Limitations
Agent Teams are still experimental, so there are several limitations beginners should know.
Session Resume Doesn't Fully Restore Teammates
Current documentation says /resume and /rewind do not restore in-process teammates.
After resuming, you may need to ask the lead to spawn new teammates.
Task Status Can Lag
A teammate may finish its actual work but fail to mark the task as completed.
That can leave dependent tasks waiting.
If this happens, check the teammate's output and update or nudge the task as necessary.
One Team Per Session
A Claude Code session has one Agent Team.
You cannot create several independent named teams inside the same session.
No Nested Teams
A teammate cannot create its own Agent Team.
The lead remains responsible for managing the team.
More Agents Mean More Coordination
Adding agents doesn't guarantee proportional speed improvements.
More teammates mean:
- more tokens,
- more messages,
- more coordination,
- more potential conflicts.
Community experiments also highlight this practical issue: simply running more agents is not the same as getting better parallel reasoning.
A Simple Beginner Workflow
If you're trying Agent Teams for the first time, use this workflow:
Step 1: Enable Agent Teams
Add:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Step 2: Choose a Parallel Task
Start with something like:
"Review this project for security, performance, and testing problems."
Step 3: Define Roles
Ask Claude for three teammates:
- Security reviewer
- Performance reviewer
- Test reviewer
Step 4: Give Them Clear Ownership
Tell each teammate exactly what to inspect.
Step 5: Let Them Investigate
Allow the teammates to work independently and communicate their findings.
Step 6: Review the Combined Result
Ask the lead to synthesize the findings and create a final action plan.
Step 7: Implement Carefully
For coding tasks, make sure teammates don't unintentionally modify the same files.
This approach gives beginners a safer way to understand what Agent Teams can actually do.
Claude Code Agent Teams: The Simple Mental Model
If the terminology feels confusing, remember this:
Single Claude Code session
One agent → one workflow.
Subagent
One main session → delegates a focused task → gets the result back.
Agent Team
One lead → multiple independent Claude Code sessions → shared coordination → direct communication → combined result.
The important idea isn't simply "more Claude agents."
The real benefit is parallel work plus coordination.
If agents don't need to communicate or coordinate, a simpler approach may be enough.
If the task naturally divides into independent workstreams and those agents benefit from exchanging information, Agent Teams become much more interesting.
Frequently Asked Questions
Are Claude Code Agent Teams the same as subagents?
No.
They overlap conceptually, but Agent Teams coordinate multiple independent Claude Code sessions around a larger task. Subagents are generally designed for focused delegated work and context isolation.
Current Claude Code documentation also allows named subagents to communicate, so the distinction should not be reduced to "subagents cannot communicate."
Are Agent Teams enabled by default?
No.
Agent Teams are currently experimental and disabled by default. You need to enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Do Agent Teams cost more?
They can use significantly more tokens than a single session because each teammate runs with its own context.
The number of active teammates therefore has a direct impact on usage.
How many teammates should I use?
For most workflows, Claude Code's current documentation recommends starting with 3–5 teammates and scaling up only when the task genuinely benefits from additional parallel workers.
Can teammates talk to each other?
Yes.
Agent Team teammates can communicate directly with each other, and the lead can also message individual teammates.
Can teammates edit the same files?
They can attempt to, but this creates a conflict risk.
The official guidance is to give teammates separate file or module ownership whenever possible.
Do Agent Teams work in non-interactive mode?
No, not as Agent Teams.
In -p non-interactive sessions, including Agent SDK sessions, Claude does not spawn teammates as Agent Teams.
Are Agent Teams ready for every project?
Not necessarily.
They are still experimental and have limitations involving session resumption, task tracking, shutdown behavior, and team structure.
For simple or sequential work, a normal Claude Code session or a subagent may be more appropriate.
Final Takeaway
Claude Code Agent Teams are best understood as a way to turn one Claude Code workflow into a coordinated group of independent Claude Code sessions.
They are most useful when a task can be divided into meaningful parallel workstreams—such as code reviews, competing debugging hypotheses, research, separate modules, or cross-layer changes.
But Agent Teams are not automatically better than a single agent.
They consume more tokens, introduce coordination overhead, and can create conflicts when agents overlap.
For beginners, the best approach is simple:
Start small. Give each teammate a clear job. Keep ownership separate. Monitor the work. And use Agent Teams only when parallel collaboration actually provides value.