Orchestrate Teams of Claude Code Sessions

1. What Is an Agent Team?

An agent team lets multiple Claude Code instances work together on one larger problem. The lead session coordinates the work, while teammates independently investigate or implement assigned tasks. Unlike ordinary subagents, teammates can communicate directly with one another.

2. Current Status

The official Claude Code documentation currently describes agent teams as experimental and disabled by default. They must be explicitly enabled before Claude can create a team.

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

You can enable the feature in your shell environment or in settings.json.

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

3. Agent Teams vs. Subagents

4. When Should You Use Agent Teams?

The strongest use cases are:

• Research and review: different teammates investigate different dimensions simultaneously.
• New modules/features: teammates own separate pieces.
• Debugging with competing hypotheses: multiple theories are tested in parallel.
• Cross-layer work: frontend, backend, and tests can be handled by different teammates.

When not to use them

• Sequential tasks where one step depends heavily on the previous step.
• Several workers must edit the same file.
• A simple one-agent task is sufficient.
• The coordination cost is larger than the benefit.

5. Enable Agent Teams

Option A — Environment variable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Option B — settings.json

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

With agent teams enabled, named agents created during interactive sessions can launch as teammates. In non-interactive -p mode, Claude does not spawn teammates; named delegation remains ordinary subagent work.

6. Start Your First Team

After enabling teams, describe the task and the teammates you want in natural language.

I'm designing a CLI tool that helps developers track TODO comments
across their codebase.

Spawn three teammates:
- one focused on UX
- one focused on technical architecture
- one playing devil's advocate

Have them explore the problem independently and then synthesize
the findings.

Claude can create the teammates, populate a shared task list when Task tools are available, and synthesize the results. Sometimes Claude may choose ordinary subagents instead; if you specifically need a team, explicitly ask for an agent team.

7. Team Architecture

8. Shared Task List

The shared task list coordinates work across the team. Tasks can be pending, in progress, or completed. Tasks can also have dependencies.

Task A: Research API
Task B: Research database
Task C: Design architecture
Task D: Implement feature
        ↑
depends on A + B + C

A task with unresolved dependencies cannot be claimed until those dependencies are completed. Agents with Task tools can also self-claim the next unassigned, unblocked task.

9. Lead Assigns vs. Self-Claim

Task claiming uses file locking to avoid race conditions when multiple teammates try to claim the same task.

10. Display Modes

Agent teams currently support two main display modes.

In-process

All teammates run inside the main terminal. Use the agent panel to select a teammate and press Enter to view and message it. This works in any terminal and is the current default.

Split panes

Each teammate gets its own terminal pane, so you can see multiple outputs simultaneously and interact directly with each pane. Split panes require tmux or iTerm2.

Configure the mode

{
  "teammateMode": "auto"
}

Or for one session:

claude --teammate-mode auto

Other documented values include in-process, tmux, and iterm2. The --teammate-mode flag is experimental.

11. iTerm2 Setup

For native iTerm2 split panes, the documentation requires the it2 CLI and the iTerm2 Python API. Enable the Python API in:

iTerm2 → Settings → General → Magic → Enable Python API

12. tmux Setup

Split-pane mode can use tmux. Install tmux through your operating system's package manager. The documentation notes that tmux has platform-specific limitations and traditionally works best on macOS.

13. Specify Teammates and Models

Claude can choose the number of teammates based on the task, or you can specify exactly what you want.

Spawn 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Claude Code selects a teammate's model using this order:

1. The model named in the spawn prompt.
2. The model from the referenced subagent definition.
3. CLAUDE_CODE_SUBAGENT_MODEL, when configured.
4. The lead's current model.

Organization model allowlists can affect the final selection. Teammates also inherit the lead's effort level.

14. Reuse Custom Subagent Definitions

A teammate can use a reusable subagent definition from project, user, plugin, or CLI scope. This lets you define roles such as security-reviewer or test-runner once.

Spawn a teammate using the security-reviewer agent type
to audit the authentication module.

The teammate can inherit configuration such as its tool list, model, and system-prompt body. The exact behavior of fields such as skills and mcpServers depends on the display mode.

15. Give Teammates Enough Context

A teammate automatically loads normal project context such as CLAUDE.md, MCP servers, and Skills. However, it does not inherit the lead's conversation history.

Good spawn prompt

Review src/auth/ for security vulnerabilities.
Focus on token handling, session management, and input validation.
The app uses JWT tokens stored in httpOnly cookies.
Report findings with severity ratings.

16. Teammates Communicate Directly

Each teammate is a full independent Claude Code session. You can message a teammate directly to give instructions, ask follow-up questions, or redirect its approach. Teammates can also message one another.

17. Security of Agent Messages

A message from another agent is treated as coming from another Claude session, not from you. A teammate cannot approve a permission request on your behalf or use another teammate's message to bypass a denied action.

In Auto mode, Claude Code also checks inter-agent messages before delivering them. Messages that attempt to relay approval or other untrusted claims can be blocked.

18. Permissions

Teammates start with the lead's permission mode. If the lead uses --dangerously-skip-permissions, teammates inherit that mode too.

After spawning, individual teammate permission modes can be changed, but per-teammate modes cannot be specified at spawn time. Permission prompts from teammates appear in the lead session.

19. Plan Before Implementation

For complex or risky tasks, start the lead in Plan Mode before spawning teammates. A teammate spawned while the lead is in Plan Mode works in read-only planning mode until its plan is ready.

Spawn an architect teammate to refactor the authentication module.

The teammate sends a plan approval request to the lead. Claude Code approves that plan in the lead session automatically; the teammate's later edits and commands still go through the normal permission system.

20. Monitor and Message Teammates

In-process mode

• Use ↑ / ↓ to select a teammate.
• Press Enter to open its transcript.
• Type to send a direct message.
• Press x on a selected teammate to stop it.
• Press Ctrl+T to toggle the task list.

Split-pane mode

Click into a teammate's pane to interact directly with its terminal.

21. Teammate Status

The agent panel shows teammates as they work, fail, or become idle. Current versions keep an idle teammate visible while another teammate is still working; once the whole panel becomes idle, idle rows can hide after a short delay.

When many teammates are idle, their rows can collapse into a single count such as 2 idle agents.

22. Shut Down a Teammate

Ask the lead to shut down a teammate by name:

Ask the researcher teammate to shut down

The lead sends a shutdown request. The teammate can approve the request and exit gracefully or reject it with an explanation. Team shared directories are cleaned up automatically when the session ends.

23. Quality Gates with Hooks

Hooks can enforce rules at important team events.

24. Team Context and Communication

Each teammate has its own context window.

Lead context
     │
     ├── Spawn prompt
     │
     ├── Teammate A context
     │       └── messages
     │
     ├── Teammate B context
     │       └── messages
     │
     └── Teammate C context
             └── messages

The lead's conversation history does not automatically transfer to teammates. Instead, teammates receive project context and the spawn prompt, then communicate findings through messages and task state.

25. Token Usage

Agent teams use significantly more tokens than a single session because each teammate is its own Claude instance with its own context. Token usage grows with the number of active teammates.

26. Choose the Right Team Size

There is no hard fixed limit, but practical limits appear quickly. More teammates mean more communication, coordination, possible conflicts, and diminishing returns.

27. Size Tasks Correctly

The documentation suggests roughly 5–6 tasks per teammate as a useful level when a larger task is being divided.

28. Avoid File Conflicts

Two teammates editing the same file can overwrite one another. Divide ownership so each teammate controls a different set of files.

Teammate A → src/frontend/
Teammate B → src/backend/
Teammate C → tests/

29. Wait for Teammates to Finish

Sometimes the lead starts implementing the solution itself before teammates have finished their work. If you want the lead to wait, tell it explicitly:

Wait for your teammates to complete their tasks before proceeding.

30. Start with Research and Review

If you are new to agent teams, begin with tasks that have clear boundaries and do not require parallel implementation:

• Pull request review
• Library research
• Bug investigation
• Competing root-cause hypotheses

These tasks demonstrate the value of parallel exploration without introducing as many file-edit conflicts.

31. Example — Parallel Code Review

Spawn three teammates to review PR #142:

- One focused on security implications
- One checking performance impact
- One validating test coverage

Have them each review and report findings.

Each teammate uses a different review lens. The lead then synthesizes the findings.

32. Example — Competing Debugging Hypotheses

Users report the app exits after one message instead of staying connected.

Spawn 5 agent teammates to investigate different hypotheses.
Have them challenge each other's theories like a scientific debate.
Update the findings document with the consensus.

The goal is to reduce anchoring: instead of accepting the first plausible explanation, independent teammates actively try to disprove competing theories.

33. Example — Cross-Layer Feature

Build the new notification feature.

Teammate A → frontend UI
Teammate B → backend API
Teammate C → tests
Teammate D → documentation

Coordinate dependencies and synthesize the final result.

This works best when each teammate owns a distinct area and dependencies are clearly represented.

34. Troubleshooting — Teammates Not Appearing

• Check whether Claude decided the task was complex enough to justify a team.
• In in-process mode, check the agent panel below the prompt.
• If rows disappeared after becoming idle, they may only be hidden.
• If split panes are requested, verify that tmux is installed and on PATH.
• For iTerm2, verify the it2 CLI and Python API setup.
• If you explicitly need a team, say “spawn an agent team” rather than merely “use agents.”

35. Troubleshooting — Claude Uses Subagents Instead

When agent teams are enabled, Claude may turn named subagents into teammates. If you want ordinary subagents instead, disable agent teams:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Settings precedence still matters: higher-precedence project/local settings or managed settings can override user settings.

36. Troubleshooting — Too Many Permission Prompts

Teammate permission requests appear in the lead session. If many teammates repeatedly perform the same safe operation, pre-approve appropriate common operations in your permission settings.

37. Troubleshooting — Agents Stop Early

A teammate may stop after an error instead of recovering. Select it and inspect its output, then either:

• Give the teammate additional instructions.
• Ask it to retry.
• Spawn a replacement teammate.

The lead itself can also decide the team is finished too early. Tell the lead to continue if tasks remain.

38. Troubleshooting — Orphaned tmux Sessions

If a tmux session remains after Claude Code exits, list tmux sessions:

tmux ls

Then terminate the team-created session:

tmux kill-session -t <session-name>

39. Limitations

• Agent teams are experimental.
• In-process teammates are not restored by normal /resume or /rewind.
• Task status can sometimes lag or fail to update.
• Shutdown can take time while a teammate finishes its current request/tool call.
• One session has exactly one team.
• Teammates cannot create their own nested teams.
• In-process teammates cannot keep background subagents alive independently of the lead process.
• The lead remains the lead for the lifetime of the session.
• All teammates start with the lead's permission mode.
• Split panes require tmux or iTerm2 and are not supported in some terminals such as VS Code's integrated terminal, Windows Terminal, and Ghostty.

40. Agent Teams vs. Other Parallel Approaches

41. Common Beginner Mistakes

1. Using agent teams for a simple task.
2. Spawning too many teammates.
3. Giving teammates tasks that edit the same files.
4. Assuming teammates inherit the lead's conversation history.
5. Forgetting to provide task-specific context in spawn prompts.
6. Not waiting for teammates before the lead starts implementation.
7. Ignoring token usage.
8. Using split panes without installing/configuring tmux or iTerm2.
9. Confusing agent teams with ordinary subagents.
10. Assuming a team survives /resume exactly as it was.

42. Best-Practice Checklist

43. Interview / Revision Questions

1. What is an agent team in Claude Code?
2. What is the role of the team lead?
3. What is the difference between a teammate and a subagent?
4. How do you enable agent teams?
5. What are the strongest use cases for agent teams?
6. What are the two display modes?
7. What does teammateMode control?
8. How are teammate models selected?
9. Do teammates inherit the lead's conversation history?
10. How do teammates communicate?
11. What are the states in the shared task list?
12. How can a teammate claim a task?
13. How do you shut down a teammate?
14. How can hooks enforce quality gates?
15. Why should you avoid same-file edits?
16. Why do agent teams cost more tokens?
17. What are the current limitations of agent teams?

44. Practice — Build Your First Agent Team

1. Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
2. Start Claude Code interactively.
3. Choose a project with three independent research questions.
4. Ask Claude to spawn three teammates with clearly separated roles.
5. Give each teammate enough context in the spawn prompt.
6. Watch the agent panel.
7. Open one teammate and message it directly.
8. Observe the shared task list.
9. Ask the lead to wait for all teammates before synthesizing.
10. Compare the team result with what a single Claude session would have produced.

45. Quick Memory Map

46. Final Takeaway

                TEAM LEAD
                    │
        ┌───────────┼───────────┐
        ↓           ↓           ↓
   Teammate A   Teammate B   Teammate C
   Research     Implement    Review
        │           │           │
        └────── Messages / Tasks ──────┘
                    ↓
              Lead synthesizes
                    ↓
               Final result