dwmkerr/claude-code-agent-teams

Claude Code Agent Teams

Coordinate multiple Claude Code instances working together as a team with shared tasks, inter-agent messaging, and centralized management.

Quick Reference

See Agent Teams Guide for the complete reference including use case examples, architecture details, and troubleshooting.

Prerequisites

Agent teams are experimental and disabled by default. Enable them:

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

When to Use Agent Teams

Best for tasks where parallel exploration adds value:

| Use Case | Why Teams Help | |----------|---------------| | Research and review | Multiple angles investigated simultaneously | | New modules or features | Each teammate owns a separate piece | | Debugging competing hypotheses | Test different theories in parallel | | Cross-layer coordination | Frontend, backend, tests each owned by a teammate |

Don't use teams for: sequential tasks, same-file edits, or work with many dependencies. Use a single session or subagents instead.

Agent Teams vs Subagents

| | Subagents | Agent Teams | |---|---|---| | Context | Results return to caller | Fully independent | | Communication | Report back only | Message each other directly | | Coordination | Main agent manages all work | Shared task list, self-coordination | | Best for | Focused tasks where only the result matters | Complex work requiring discussion | | Token cost | Lower | Higher (each teammate is a separate instance) |

Use subagents for quick focused workers. Use agent teams when teammates need to share findings, challenge each other, and coordinate independently.

Starting a Team

Tell Claude to create a team in natural language:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.

Claude creates the team, spawns teammates, and coordinates work.

Display Modes

| Mode | Description | Requirements | |------|-------------|-------------| | in-process | All teammates in main terminal, Shift+Down to cycle | Any terminal | | tmux / split panes | Each teammate in its own pane | tmux or iTerm2 | | auto (default) | Split panes if in tmux, otherwise in-process | — |

Override per-session:

claude --teammate-mode in-process

Or in settings:

{
  "teammateMode": "in-process"
}

Controlling the Team

Specify teammates and models

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

Require plan approval

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

The lead reviews plans and approves or rejects with feedback.

Talk to teammates directly

• In-process: Shift+Down to cycle, Enter to view, Escape to interrupt
• Split panes: Click into a teammate's pane

Task management

Tasks have three states: pending, in progress, completed. Tasks can depend on other tasks. The lead assigns tasks or teammates self-claim. Press Ctrl+T to toggle the task list.

Shut down and clean up

Ask the researcher teammate to shut down

When done:

Clean up the team

Always use the lead to clean up. Shut down all teammates first.

Quality Gates with Hooks

• TeammateIdle — runs when a teammate is about to go idle. Exit code 2 sends feedback and keeps them working.
• TaskCompleted — runs when a task is marked complete. Exit code 2 prevents completion and sends feedback.

Best Practices

1. Give enough context — teammates don't inherit the lead's conversation history. Include details in spawn prompts.
2. Start with 3-5 teammates — balances parallelism with coordination overhead.
3. 5-6 tasks per teammate — keeps everyone productive.
4. Avoid file conflicts — each teammate should own different files.
5. Monitor and steer — check progress, redirect approaches that aren't working.
6. Start with research/review — before trying parallel implementation.

Limitations

• No session resumption for in-process teammates (/resume, /rewind don't restore them)
• Task status can lag — check and update manually if stuck
• One team per session
• No nested teams (teammates can't spawn their own teams)
• Lead is fixed for the team's lifetime
• All teammates start with the lead's permission mode
• Split panes require tmux or iTerm2 (not supported in VS Code terminal, Windows Terminal, or Ghostty)

Architecture

| Component | Role | |-----------|------| | Team lead | Main session that creates team, spawns teammates, coordinates | | Teammates | Separate Claude Code instances working on assigned tasks | | Task list | Shared work items that teammates claim and complete | | Mailbox | Messaging system for inter-agent communication |

Storage locations:

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

Attribution

Content adapted from Orchestrate teams of Claude Code sessions (Anthropic documentation).