Why This Matters#

Sometimes a task is too big for a single agent. Imagine renovating an apartment: an electrician, plumber, and painter work in parallel, each in their own zone, but coordinating their actions.

Agent Teams is a Claude Code feature where multiple Claude instances work simultaneously on different aspects of a task:

• 🔀 Parallel execution — multiple tasks run at the same time
• 💬 Inter-agent communication — team members can exchange information
• 🎯 Specialization — each agent is responsible for its own area
• 👤 Direct access — you can communicate with any team member directly

Agent Teams vs Sub-agents#

Claude Code has two ways of working in parallel. It’s important to understand the difference:

Rule of thumb: use sub-agents for simple tasks, Agent Teams for complex ones requiring coordination.

Enabling Agent Teams#

Agent Teams are disabled by default. Enable them using one of these methods:

Method 1: Via Environment Variable#

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Method 2: Via settings.json#

Add to the .claude/settings.json file:

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

Launching an Agent Team#

Once enabled, simply describe the task and team structure in natural language:

Example 1: Research and Review#

Create a team of 3 agents:
1. First agent — researches the project architecture and documents it
2. Second agent — checks the code for security issues
3. Third agent — checks test coverage

Each should work in parallel and share their results.

Example 2: Feature Implementation#

I need a team to implement an authentication system:
- Agent "backend" — creates API endpoints for login/logout/register
- Agent "frontend" — creates UI for login and registration forms
- Agent "tests" — writes tests for both parts

Coordinate with each other on API contracts.

Example 3: Debugging with Competing Hypotheses#

There's a bug: the app freezes when uploading files > 10MB.

Create a debugging team:
- Agent 1: investigates the memory leak hypothesis
- Agent 2: investigates the network timeout hypothesis
- Agent 3: investigates the buffering issue hypothesis

Each should explore their hypothesis and report findings.

Managing the Team#

Viewing Status#

Claude Code will show the status of each team member: who is working on what, who has finished.

Communicating with a Specific Agent#

You can address any team member directly, not just through the leader.

Assigning Tasks#

The team leader coordinates the work, but you can intervene and redirect tasks.

When Agent Teams Are Effective#

✅ Good scenarios:

• Investigating different aspects of a problem in parallel
• New modules/features where agents work in different files
• Debugging with multiple hypotheses simultaneously
• Cross-layer work: frontend + backend + tests

❌ Poor scenarios:

• Sequential tasks (where each step depends on the previous one)
• Working in the same file (change conflicts)
• Tasks with many dependencies
• Simple tasks (excessive coordination overhead)

Best Practices#

1. Clear roles — each agent should have a well-defined area of responsibility
2. Minimal overlap — agents should not edit the same files
3. Specific tasks — vague descriptions lead to duplicated work
4. Mind the tokens — each agent uses tokens separately, teams cost more
5. Start small — try 2-3 agents before creating a large team

Lesson Summary#

• Agent Teams are multiple Claude Code instances working in parallel
• Unlike sub-agents, team members can communicate with each other
• Enabled via the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 variable
• Describe the team and tasks in natural language
• Works best for parallel tasks without file overlaps
• Don’t use for sequential tasks — it will be more expensive and slower
• Each agent is a separate session, token usage is higher