Claude Code Agent Teams: The Complete Guide from Solo Coding to Team Collaboration

高效码农

3 hours ago

Claude Code Agent Teams: The Complete Guide from Solo Coding to Team Collaboration

Core Question: What are Claude Code Agent Teams, and how do they change the way we interact with code?
Answer: This is a native multi-agent orchestration system that transforms traditional single-threaded task processing into a “team collaboration” mode coordinated by a lead agent, capable of complex协同 development without any plugins or custom skills.

In the realm of software development, efficiency gains often stem from changes in collaboration models. The OpenClaw community was the first to explore the possibility of orchestrating multiple Claude Code sessions through custom skills, achieving task coordination, context sharing, and parallel execution among agents. This innovation clearly caught Anthropic’s attention, as they have now natively integrated this functionality into Claude Code, officially naming it “Agent Teams.”

It is akin to shifting from hiring a solo freelancer to hiring a project manager who comes with a full construction crew. Previously, giving Claude Code a task meant it would complete step one, then step two, working like an employee capable only of serial work. Now, with Agent Teams enabled, a lead agent takes over your requirement, breaks it down, and spins up multiple teammates to work simultaneously. They don’t just report to the lead; they communicate directly with each other and share findings.

This is currently a feature in Research Preview, unknown to most. This guide will delve deep into how to install, configure, and correctly use this powerful new tool, helping you switch from a single-threaded mindset to a multi-threaded team collaboration workflow.

From Solo to Team: Core Concepts Explained

Core Question: How does the working mechanism of Agent Teams fundamentally differ from the traditional single-agent model?
Answer: In the traditional model, agents complete tasks sequentially and independently; in the Agent Teams model, roles are divided between a “Lead Agent” and “Teammates,” supporting parallel task processing and context isolation.

In the past, Claude Code worked like a dedicated solo developer. You issued a command, and it executed the first line of code, moved to the second, and so on. This linear, serial working style is stable but results in a linear accumulation of time when facing complex projects.

Agent Teams completely break this limit. When you describe a goal, it is no longer one agent grinding away alone. Instead, a lead agent first reviews the task, decomposes it into multiple independent modules, and then spins up a separate teammate for each module.

Scenario Example:
Suppose you are developing a new payment gateway feature.

Traditional Mode: One agent writes the API interface first, then the database model, and finally the unit tests—sequentially.
Agent Teams Mode: The lead agent assigns tasks—Teammate A handles the API interface, Teammate B handles the database model, and Teammate C writes unit tests. All three work simultaneously in their own context windows, without interfering with each other, and finally, the lead agent integrates the results.

In this mode, each teammate has an independent context window and workspace. They don’t just report to the lead agent; they can exchange ideas directly via messages. For example, if the API teammate finds an issue with the database field design, they can notify the database teammate directly without going through the lead agent layer by layer. The lead agent always maintains a global perspective, managing the shared task list and performing the final integration once teammates finish their work.

Deep Dive: The Essential Difference Between Sub-agents and Agent Teams

Core Question: Since we already have sub-agents, why do we need Agent Teams?
Answer: Sub-agents are cheap, one-way assistants focused on single tasks; Agent Teams are expensive, two-way interactive professional teams focused on engineering requiring complex collaboration.

If you are a long-time Claude Code user, you may have already used “sub-agents.” They usually spawn within a session, complete a specific task (like reading a file or searching docs), and return the result. This approach is simple, effective, and relatively saves tokens.

But Agent Teams are a completely different “species.” We can clearly see their differences in the table below:

Feature	Sub-agents	Agent Teams
Independence & Context	Runs inside the main session, context depends on main session	Each teammate is a fully independent Claude Code session with its own context window
Interaction Mode	One-way report: Sub-agent -> Lead Agent	Multi-way interaction: Teammate <-> Teammate, Teammate <-> Lead Agent
Collaboration Ability	None, only executes isolated assigned tasks	Strong, self-coordinates via shared task list and direct messaging
Cost	Lower	Higher (since multiple sessions run simultaneously)
Use Case	Quick queries, simple tool calls	Complex problem solving, parallel development, code review

Which one should you use?

The key to choosing is: Do your workers need to communicate with each other?

Use Sub-agents: If you just need a quick result, like “Help me check the usage of this function,” no extra coordination is needed. It’s like sending an assistant to get a cup of coffee; they just bring it back.
Use Agent Teams: If the work benefits from collaboration. It’s like putting a group of specialists in a room to solve a tough problem together. Although the cost is higher, for complex, multi-part work, a single agent would take significantly longer than a team.

“

💡 Expert Reflection: The Trade-off Between Cost and Value
From an engineering economics perspective, Agent Teams introduces a new dimension of cost: communication overhead versus parallel benefit. In AI programming, we are used to linear thinking (token consumption is proportional to time). Agent Teams teaches us that by paying extra “parallel computing costs” (running multiple instances at once), we can exchange it for exponential time compression. This is not just a tech upgrade, but a paradigm shift in AI-assisted development thinking.

Strategic Decisions: When is Agent Teams Most Cost-Effective?

Core Question: In what scenarios is using Agent Teams wise, and when is it a waste of resources?
Answer: Use it when tasks can be decomposed and parallel exploration adds significant value (e.g., competing hypothesis debugging, cross-layer development); avoid it for strongly sequential tasks or simple tasks.

Agent Teams is not a “use for everything” feature. Since it adds coordination overhead and burns tokens significantly faster than a single session, you need to be strategic about when to spin one up.

Best Use Cases

Research and Review:
When investigating a problem from multiple angles. For example, multiple teammates investigate different parts of the codebase simultaneously (security, performance, readability) and then compare notes. This parallel exploration drastically reduces blind spots.
Feature Building:
When each teammate can own a separate module or file. For example, Teammate A handles the frontend component, Teammate B handles the backend logic, and Teammate C handles the data layer. Everyone owns their own territory without stepping on toes.
Debugging—The Most Exciting Scenario:
This is where Agent Teams shines the most. In traditional debugging, one agent might go down a wrong theoretical path, wasting time. With Agent Teams, you can spin up multiple teammates to test competing hypotheses in parallel.
- Scenario: The program crashes.
- Teammate A: Verifies the “memory leak” hypothesis.
- Teammate B: Verifies the “race condition” hypothesis.
- Result: Whoever finds the answer first wins, and the others can stop immediately.

Scenarios to Avoid

Sequentially Dependent Tasks:
If step two strictly depends on the result of step one, parallelization offers no benefit and only adds complexity to context synchronization.
Same-File Editing:
Having two teammates edit the same file is disastrous. It leads to version conflicts and overwrites. Ensure tasks are split so each teammate owns a separate set of files.
Simple Tasks:
If the cost of coordinating the task is higher than just letting one agent handle it quickly, don’t use a team.

Image Source: Unsplash

Installation & Configuration: Enable the Experimental Feature in 30 Seconds

Core Question: How do I enable the Agent Teams feature in my environment?
Answer: Enable it by adding a specific configuration to settings.json or setting the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS.

Since Agent Teams is currently experimental, it is disabled by default. You must manually turn it on before use. There are two methods, and you can choose based on your preference.

Method 1: Modify settings.json (Recommended)

This is the cleanest method, and the configuration persists. Find your Claude Code configuration file settings.json and add the following:

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

Ensure the JSON format is correct, especially commas and brackets. Save the file and restart Claude Code.

Method 2: Set Shell Environment Variable

If you don’t want to edit the config file or just want to test it temporarily in the current session, you can set the environment variable directly in your Shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

This method expires when the current terminal session closes.

Verify Configuration

After completing either step, Claude Code will recognize Agent Teams commands. At this point, you can start trying to create your first team. Note that as an experimental feature, official documentation may update, but the configuration above is the standard way to enable it right now.

“

💡 Expert Reflection: The Charm and Risk of Experimental Features
As an early adopter, using experimental features always comes with the risk of “rough edges.” It’s like putting software into production during the Alpha phase; there might be bugs, but you gain the efficiency dividend of the first-mover advantage. Controlling features via settings.json reflects the control Anthropic gives advanced users, but also reminds us: this is a rapidly evolving tool.

Starting Your First Agent Team

Core Question: How do I correctly start and assign tasks to an Agent Team via prompts?
Answer: Use natural language to describe requirements, clearly specifying independent roles for teammates (e.g., UX, Architecture), avoiding task overlap, allowing the lead agent to generate the team and start working.

You don’t need to learn any special programming syntax to start a team. Just use clear natural language to tell Claude what you want and instruct it to create a team.

Prompt Engineering: Clear Roles are Key

A successful startup prompt hinges on giving the lead agent clear, independent role definitions. If the task is too vague, the lead agent has to spend a lot of tokens figuring out the structure itself, which usually leads to less focused results.

Best Practice Example:

Suppose you are designing a CLI tool to help developers track TODO comments in their codebase.

“

“I am designing a CLI tool to help developers track TODO comments in their codebase. Please create an agent team to explore this from different angles: one teammate focusing on User Experience (UX), one on Technical Architecture, and another playing ‘Devil’s Advocate’ to challenge the ideas.”

In this example, you have defined three independent dimensions: UX, Architecture, and Critical Review. This is much more effective than just saying “Help me design a tool.”

Specifying Teammate Count and Model

You can further control the team size and the model used:

“

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

Display Mode Selection

Once the team starts running, you have two display modes to choose from:

In-Process Mode (Default):
All teammates run inside the main terminal. You can use Shift + Up or Shift + Down to cycle through different teammate outputs. This mode has the best compatibility.
Split-Pane Mode:
In this mode, each teammate gets their own pane, and you can see everyone’s output simultaneously. However, this requires terminal support for tmux or iTerm2. Note: VS Code’s integrated terminal, Windows Terminal, or Ghostty do not currently support split-pane mode; only the default in-process mode is available there.

Runtime Control: How to Command Your Team

Core Question: How do I intervene, communicate, and manage tasks while the team is running?
Answer: You can talk directly to any teammate, use Delegate Mode to restrict the lead agent to coordination only, and manage workflows via the task list.

Once your team is up and running, as the “manager,” you need to master a few key control operations to ensure the project proceeds as expected.

1. Communicate Directly with Teammates

You don’t need to pass messages through the lead agent. In in-process mode, press Shift + Up or Shift + Down to select a teammate and just start typing. In split-pane mode, just click into their pane. This is very useful for course correction or follow-up questions.

2. Use Delegate Mode

This is an important feature that solves a common pain point. Sometimes, the lead agent decides “Since the task is urgent, I’ll just do it myself,” rather than waiting for teammates. This defeats the purpose of using a team.

Delegate Mode locks the lead agent into a “coordination-only” state. When enabled, the lead agent can only spawn teammates, assign tasks, send messages, and manage the task list; it cannot personally write code.

How to use: Press Shift + Tab once the team is running to toggle this mode.

3. Task Assignment and Claiming

In Agent Teams, task management is flexible:

Lead Assignment: The lead specifies who does what.
Self-Claiming: When a teammate finishes their current task, they automatically check the shared task list and claim the next unassigned one.

If you need more control, just tell the lead agent which specific task goes to which teammate.

4. Shutdown and Cleanup

Resource management is important. When a teammate finishes their work, you can ask the lead agent to shut them down.

The lead agent sends a shutdown request.
The teammate confirms.
The teammate exits gracefully.

When the entire team is done with all tasks, tell the lead agent to “clean up,” and it will remove all shared team resources. Remember: Ensure all teammates are shut down before running cleanup.

Best Practices: Practical Tips to Avoid Wasting Tokens

Core Question: How can I maximize efficiency and minimize costs when using Agent Teams?
Answer: Provide detailed spawn prompts, size tasks reasonably, ensure file isolation, and start practicing with non-code review tasks.

Agent Teams burn through tokens extremely fast because they run multiple sessions in parallel. The following tips will save you money and frustration.

1. Provide Detailed Spawn Prompts

Teammates automatically load project context from your project directory and MCP servers, but they do not inherit the lead agent’s conversation history.

This means if a teammate needs specific background information to do their job well, you must include that information in the prompt when the lead agent spawns them. The more specific you are upfront, the less back-and-forth they will need.

2. Control Task Granularity Reasonably

Too Fine-grained: If tasks are too small (e.g., “rename a variable”), the coordination overhead costs more than the task itself.
Too Coarse: If tasks are too large, teammates work too long without check-ins, increasing the risk of wasted effort.
Sweet Spot: Self-contained task units that produce a clear deliverable, such as “finish this function,” “generate this test file,” or “complete the code review for this module.”

3. Strict File Isolation

Never let two teammates edit the same file. This leads to overwrite conflicts and is a headache you don’t need. When breaking down work, ensure each teammate owns their own set of files.

4. Learning Curve: Start with Reviews

If you are new to Agent Teams, don’t start by trying to build complex code in parallel.建议 starting with research and review tasks.

Have teammates review a Pull Request (PR) from different angles.
Have teammates investigate a bug with competing theories.

These tasks let you see the value of parallel work without the coordination complexity of writing code simultaneously.

5. Check In Regularly

Don’t let the team run unattended for too long. Check in on progress regularly, especially to prevent one teammate from going down a path that isn’t productive.

“

💡 Expert Reflection: The Hidden Advantage of Context Isolation
Many people think it’s a defect that teammates don’t inherit the lead’s history, but I think it’s a brilliant architectural design. If every teammate inherited the full history, context windows would explode instantly, and costs would spiral out of control. This “context isolation” forces us as users to express our intent more clearly, essentially training us to write better Prompts. It also keeps each teammate “lightweight” and “focused,” just like in an efficient human team where not everyone needs to know every bit of small talk from the first five minutes of a meeting, just the background of the task assigned to them.

Current Limitations: Don’t Blame the Tool for These

Core Question: What are the known imperfections of the current Agent Teams?
Answer: In-process teammates don’t support session resumption, task status can lag, there’s a limit of one team per session, and split-pane mode has specific terminal requirements.

As a Research Preview feature, Agent Teams has some rough edges. Knowing these in advance can save you from thinking it’s your mistake when you encounter them.

Session Resumption Unsupported:
If you use /resume or /rewind, your teammates won’t come back. The lead agent might try to message them, but they won’t exist anymore. If this happens, just tell the lead agent to spawn new ones.
Task Status Lag:
Sometimes a teammate finishes the work but forgets to mark the task as “completed.” This blocks any tasks that depend on it. If things look stuck, check if the work is actually done, then manually update the status or tell the lead agent to nudge the teammate.
Architectural Limitations:
- You can only run one team per session.
- Teammates cannot spawn their own teams (no nesting).
- The session that creates the team remains the lead for its entire lifetime; you can’t promote a teammate or transfer leadership mid-session.
Platform Compatibility:
Split-pane mode only supports tmux or iTerm2. VS Code Integrated Terminal, Windows Terminal, or Ghostty are not supported yet. However, the default in-process mode works everywhere.

Understanding these limitations allows you to plan your workflow more calmly, treating them as boundary conditions of the current version rather than insurmountable obstacles.

Conclusion & Outlook

Core Question: What is the future development direction of Agent Teams, and is it worth investing time in learning now?
Answer: This is a baseline feature in rapid iteration; as coordination and shutdown behaviors improve, it will become a standard configuration for Claude Code, and building muscle memory now will bring a first-mover advantage.

Agent Teams is currently in Research Preview, which means Anthropic is actively developing it. What you see today is a baseline, not the ceiling. As they iron out the rough edges around session resumption, task coordination, and shutdown behavior, this feature is set to become a standard part of how people work with Claude Code.

Those who install this early and start building muscle memory now will have a significant efficiency edge when it moves out of preview and becomes a default feature. Just as the leap from solo programming to pair programming, the evolution from single-agent to multi-agent teams may well be the next milestone in AI-assisted development.

Practical Summary / Action Checklist

To help you get started quickly, here is a summary of operational points based on this guide:

Before You Enable

[ ] Open settings.json or set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to “1”.
[ ] Ensure you are using a supported terminal (tmux or iTerm2 required if you need split-pane functionality).

Team Startup

[ ] Use natural language to clearly specify independent roles for teammates (e.g., UX, Architecture, Testing).
[ ] You can specify the model (e.g., Sonnet) and the number of teammates.
[ ] Avoid vague task definitions to ensure the lead agent can assign them directly.

Runtime Management

[ ] Use Shift + Up/Down to switch between teammates in in-process mode.
[ ] Press Shift + Tab to toggle Delegate Mode on/off, forcing the lead agent to only coordinate.
[ ] Select a teammate to talk to them directly; no need to pass messages through the lead agent.
[ ] Ensure different teammates edit different files to prevent conflicts.

Best Practices

[ ] Include detailed background in the prompt when spawning teammates, as they do not inherit lead agent history.
[ ] Start practicing with code review or investigation tasks before moving to parallel development.
[ ] Check task status regularly to prevent teammates from getting stuck in an unmarked completion state.
[ ] Manually instruct to shutdown teammates and clean up resources when tasks are done.

One-page Summary

Concept	Key Points
Definition	Native multi-agent system; Lead agent coordinates, teammates work in parallel with independent context.
Vs. Sub-agents	Sub-agents = One-way assistant (Cheap); Agent Teams = Collaborative experts (Expensive, Powerful).
How to Enable	Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"`.
Startup Command	Define roles clearly (e.g., “A does UX, B does Architecture, C does Testing”).
Display Modes	In-process (Universal, switch windows); Split-pane (Requires tmux/iTerm2).
Shortcuts	`Shift+Up/Down` (Switch teammates), `Shift+Tab` (Toggle Delegate Mode).
Best Scenarios	Debugging (competing hypotheses), Cross-layer development, Multi-dimensional code review.
Pitfalls	Avoid same-file edits; Avoid strongly sequential tasks; Watch token consumption.
Current Limits	No session resume support; Status may lag; One team per session limit.

Frequently Asked Questions (FAQ)

What is the essential difference between Agent Teams and normal sub-agents?
Each teammate in Agent Teams is an independent session with its own context, and teammates can communicate and collaborate directly with each other two-way; sub-agents merely execute simple one-way tasks inside the main session and cannot communicate with each other.
How do I enable the Agent Teams feature in Claude Code?
You need to add the configuration CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" to your settings.json file, or set that environment variable in your Shell.
Will using Agent Teams consume more tokens?
Yes, because it runs multiple independent Claude Code sessions simultaneously, the token consumption rate will be much faster than a single session. It is recommended for complex tasks.
What should I watch out for if I want multiple teammates writing code at the same time?
The most important thing is to ensure each teammate is responsible for editing different files. If two teammates modify the same file at the same time, it will lead to code overwrites and conflicts.
What should I do if a teammate finishes a task but doesn’t update the status?
This is a known limitation of the current preview version. You can manually check if the work is done, then tell the lead agent to update the status, or remind the teammate to confirm.
Can I use split-pane mode to view teammates in the VS Code integrated terminal?
No. Currently, split-pane mode only supports tmux or iTerm2. In VS Code, you can only use the default in-process mode and switch teammate views via keyboard shortcuts.
Sometimes the lead agent goes and writes code itself instead of assigning it to teammates, how do I solve this?
You can press Shift + Tab to turn on “Delegate Mode.” This locks the lead agent so it can only perform coordination and cannot execute code tasks personally.