Agent Teams Orchestration

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

References

• references/full-docs.md — architecture, tools, config, permissions, and limitations
• references/use-case-templates.md — ready-to-use prompt templates with spawn examples

Prerequisites

• Claude Code v2.1.32+
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json env section
• For split panes: tmux or iTerm2 (optional — in-process mode works anywhere)

Decision: Agent Team vs Subagents vs Single Session

Evaluate the task before creating a team:

Create an agent team when:

• Work partitions into 3-5 independent parallel tracks
• Multiple perspectives add value (review, research, debugging)
• Teammates need to discuss, challenge, or coordinate with each other
• Each teammate owns different files with no overlap

Use subagents instead when:

• Workers only need to report results back — no inter-agent discussion
• Tasks are quick and focused
• The result matters, not the collaboration

Use a single session when:

• Tasks are sequential or heavily interdependent
• Work involves editing the same files
• The task is routine (teams have significant token overhead)

Workflow

1. Analyze the Task

Identify:

1. Can this split into 3-5 independent tracks?
2. What files/directories does each track own?
3. Are there dependencies between tracks?
4. Will teammates need to discuss findings or just report back?

If the answer to #4 is "just report back," use subagents instead.

2. Design the Team

• 3-5 teammates for most workflows (diminishing returns beyond that)
• 5-6 tasks per teammate to keep everyone productive
• Name teammates descriptively (e.g., "security-reviewer", "frontend-dev")
• Partition file ownership — no two teammates editing the same file

3. Write Spawn Prompts

Teammates do NOT inherit the lead's conversation history. The spawn prompt is their only context. Include:

• What to do and why
• Specific files/directories they own
• Technical context (frameworks, patterns, constraints)
• Who to coordinate with and what to report
• Whether plan approval is required

Example:

Spawn a teammate named "api-dev" with the prompt: "Own the Express API
layer at src/api/. Build the new /users endpoint with JWT auth middleware.
The app uses Prisma for DB access and Zod for validation. Coordinate with
frontend-dev on the request/response schema before implementing. Report
blockers to the lead."

4. Coordinate and Monitor

• Create tasks with explicit dependency chains when needed
• Require plan approval for risky changes: "Only approve plans that include test coverage"
• Let teammates self-claim independent tasks from the shared list
• If the lead starts implementing instead of delegating, tell it: "Wait for your teammates to complete their tasks before proceeding"

5. Clean Up

Always clean up via the lead (never via teammates):

1. Shut down all teammates: "Ask [name] to shut down"
2. Clean up the team: "Clean up the team"

Guardrails

• Partition file ownership clearly — two teammates on the same file means overwrites
• Include full context in spawn prompts — history does not carry over
• Start with read-only tasks (review, research) before parallel implementation
• Pre-approve common tool permissions before spawning to reduce interruptions
• Token usage scales linearly with teammate count — size teams appropriately

See references/full-docs.md for architecture details, display modes, hooks, permissions, and known limitations. See references/use-case-templates.md for ready-to-use prompt templates.