Agent Teams — Multi-Agent Orchestration

Until now, every technique you've learned has focused on a single Claude Code session doing work on its own. That model works well for focused tasks, but some projects demand parallel exploration -- investigating multiple hypotheses at once, building independent modules simultaneously, or reviewing code from several angles in parallel. Agent teams let you coordinate multiple Claude Code instances working together, each with its own context window, communicating through a shared task list and direct messaging.

This lesson covers everything you need to orchestrate multi-agent workflows: creating teams, managing tasks, communication patterns, delegate mode, and best practices for avoiding the pitfalls of parallel work.

When to Use Agent Teams

Agent teams are not a replacement for single-session work -- they're a specialized tool for tasks where parallel exploration adds genuine value. They consume significantly more tokens than a single session, so the coordination overhead needs to be justified.

Strong use cases for agent teams:

• Research and review -- Multiple teammates investigate different aspects of a problem simultaneously, then share and challenge each other's findings
• New modules or features -- Each teammate owns a separate piece of the project without stepping on each other's files
• Debugging with competing hypotheses -- Teammates test different theories in parallel and converge on the answer faster
• Cross-layer coordination -- Changes that span frontend, backend, and tests, each owned by a different teammate

When to stick with a single session or subagents:

• Sequential tasks where each step depends on the previous one
• Edits concentrated in the same files (two agents editing the same file leads to overwrites)
• Routine tasks where coordination overhead would exceed the benefit
• Work with many tight dependencies between steps

Enabling Agent Teams

Agent teams are experimental and disabled by default. Enable them by setting an environment variable in your shell or through settings.json:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or set it directly in your terminal session:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Once enabled, you can ask Claude to create teams in natural language.

Team Architecture

Every agent team has four components:

The team lead is always the session that created the team. You cannot promote a teammate to lead or transfer leadership. Each teammate loads the same project context as a regular session -- CLAUDE.md, MCP servers, and skills -- plus a spawn prompt from the lead. The lead's conversation history does not carry over to teammates.

Teams and tasks are stored locally:

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

Creating a Team

Tell Claude what you need and describe the team structure in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.

Create an agent team to build the new notification system.
Spawn three teammates:
- A backend engineer to implement the API endpoints
- A frontend engineer to build the notification UI components
- A test engineer to write integration tests

Use Sonnet for each teammate.

Claude will:

1. Create a team with a shared task list
2. Spawn teammates for each role
3. Break the work into tasks and assign them
4. Coordinate progress and synthesize results
5. Clean up the team when finished

You can also let Claude decide the team structure. Describe the task and ask Claude to figure out what teammates are needed:

I need to investigate why our WebSocket connections keep dropping after 30
seconds. Create an agent team to explore this from different angles.

Claude might spawn teammates focused on server configuration, client-side reconnection logic, and network middleware inspection -- whatever makes sense for the problem.

Task Management

The shared task list is the coordination backbone of every agent team. Tasks move through three states: pending, in_progress, and completed. Tasks can also declare dependencies on other tasks, and a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.

How Tasks Flow

Sizing Tasks Appropriately

Getting task granularity right is critical for agent team effectiveness:

• Too small: Coordination overhead exceeds the benefit. Creating a task to rename a single variable is wasteful.
• Too large: Teammates work too long without check-ins, increasing the risk of wasted effort if they go down the wrong path.
• Just right: Self-contained units that produce a clear deliverable -- a function, a test file, a review, or a module.

Communication Patterns

Teammates communicate through a built-in messaging system with two modes:

Direct Messages

Send a message to one specific teammate. This is the default and preferred communication method:

Tell the backend engineer to expose the notification count
as a separate endpoint so the frontend can poll it.

The lead uses the SendMessage tool with a recipient and content. Messages are delivered automatically -- no polling required.

Broadcasts

Send the same message to every teammate simultaneously. Broadcasts are expensive because each one sends a separate message to every teammate, scaling linearly with team size.

Broadcast to all teammates: we've decided to use Server-Sent Events
instead of WebSockets. Adjust your implementations accordingly.

Use broadcasts only for critical announcements that genuinely affect every teammate -- like a major design decision change or a blocking issue that halts all work. For everything else, use direct messages.

Idle Notifications

When a teammate finishes its current work and stops, it automatically notifies the lead. This lets the lead know when teammates are available for new tasks or when all work is complete.

Talking to Teammates Directly

You can bypass the lead and message any teammate directly:

• In-process mode: Press Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn.
• Split-pane mode: Click into a teammate's pane to interact with their session directly.

This is useful when you want to give a teammate additional instructions, ask follow-up questions, or redirect their approach without routing through the lead.

Delegate Mode

By default, the team lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode prevents this by restricting the lead to coordination-only tools: spawning teammates, sending messages, shutting down teammates, and managing tasks.

Enable delegate mode by pressing Shift+Tab to cycle into it after starting a team.

Delegate mode is valuable when:

• The work is clearly divided among teammates and the lead shouldn't touch code
• You want the lead to focus entirely on orchestration -- breaking down work, assigning tasks, reviewing results
• Teammates have specialized roles and the lead's job is purely coordination

Without delegate mode, you may need to remind the lead to wait:

Wait for your teammates to complete their tasks before proceeding.
Don't implement anything yourself.

Display Modes

Agent teams support two display modes that control how teammate activity appears in your terminal:

In-Process Mode

All teammates run inside your main terminal. Navigate between them with Shift+Up/Down. This is the default and works in any terminal with no extra setup.

Press Ctrl+T to toggle the task list view.

Split-Pane Mode

Each teammate gets its own terminal pane. You can see everyone's output simultaneously and click into any pane to interact directly. This requires either tmux or iTerm2 with the it2 CLI.

Configure the display mode in settings.json:

{
  "teammateMode": "in-process"
}

Or override for a single session:

claude --teammate-mode in-process

The "auto" setting (default) uses split panes if you're already in a tmux session, and in-process otherwise.

Plan Approval for Teammates

For complex or risky tasks, you can require a teammate to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:

Spawn an architect teammate to redesign the database schema.
Require plan approval before they make any changes.

When the teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves (teammate exits plan mode and begins implementation) or rejects with feedback (teammate revises and resubmits).

You can influence the lead's approval criteria:

Only approve plans that include test coverage for edge cases.
Reject any plan that modifies the existing API contract.

Git Worktrees for Parallel Development

When multiple teammates need to edit files in the same repository, file conflicts become a real risk. Git worktrees solve this by giving each teammate its own working directory while sharing the same Git history.

A worktree is a separate checkout of your repository at a different path. Each teammate can work in their own worktree, make commits on separate branches, and merge results when finished -- without ever overwriting each other's changes.

# Create worktrees for each teammate
git worktree add ../project-backend feature/backend-notifications
git worktree add ../project-frontend feature/frontend-notifications
git worktree add ../project-tests feature/test-notifications

Even without worktrees, the simplest conflict-prevention strategy is file ownership: break the work so each teammate owns a different set of files. Two teammates should never edit the same file.

Quality Gates with Hooks

Use hooks to enforce rules when teammates finish work:

• TeammateIdle: Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working. Use this to check if a teammate's work meets your standards before they stop.
• TaskCompleted: Runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback. Use this to enforce quality checks like "all tests must pass" or "no linting errors."

Shutting Down and Cleaning Up

Shutting Down Teammates

To gracefully end a teammate's session:

Ask the researcher teammate to shut down.

The lead sends a shutdown request. The teammate can approve (exits gracefully) or reject with an explanation (e.g., "Still working on task #3, need 5 more minutes"). Teammates finish their current tool call before shutting down, so this may take a moment.

Cleaning Up the Team

When all work is done, ask the lead to clean up:

Clean up the team.

This removes shared team resources. The lead checks for active teammates and fails if any are still running -- shut them all down first. Always use the lead for cleanup, not individual teammates.

Practical Example: Investigating a Bug

Here's a real-world scenario showing agent teams in action:

Users report that the app disconnects after exactly one message.
Create an agent team with 4 teammates to investigate different hypotheses:

1. A WebSocket expert to check the connection lifecycle and heartbeat config
2. A middleware investigator to trace the request through all middleware layers
3. A client-side debugger to inspect the frontend reconnection logic
4. A load-balancer analyst to check proxy timeout settings

Have them discuss their findings with each other and challenge each
other's theories. Update FINDINGS.md with whatever consensus emerges.

This works because each hypothesis is independent, teammates can explore without waiting on each other, and the adversarial structure (challenging each other's theories) fights the anchoring bias that a single investigator would have.

Common Pitfalls and Troubleshooting

Current Limitations

Agent teams are experimental. Be aware of these constraints:

• No session resumption for in-process teammates -- /resume and /rewind don't restore them
• One team per session -- clean up the current team before starting a new one
• No nested teams -- teammates cannot spawn their own teams
• Lead is fixed -- the creating session is lead for the team's lifetime
• Permissions set at spawn -- all teammates start with the lead's permission mode (changeable individually after spawning, but not at spawn time)
• Split panes require tmux or iTerm2 -- not supported in VS Code terminal, Windows Terminal, or Ghostty

Next Steps

You've learned to orchestrate teams of AI agents for parallel, complex work. In the next lesson, we'll explore CI/CD integration, where you'll learn to embed Claude Code into your continuous integration pipelines for automated code review, test generation, and deployment assistance.

Resources:

• Agent Teams Documentation
• Subagents Documentation
• Git Worktrees Guide
• Hooks Reference