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).