Agent Teams for Application Development
Agent teams let you coordinate multiple Claude Code sessions working together on complex tasks. One session acts as the team lead coordinating work, while teammates work independently in their own context windows and communicate directly with each other.
When to Use Agent Teams
Agent teams are most effective when parallel exploration adds real value:
| Use Case | Why Teams Excel |
|---|---|
| Research & Discovery | Multiple teammates investigate different aspects simultaneously |
| Feature Development | Teammates each own a separate module without stepping on each other |
| Code Review & QA | Reviewers apply different lenses (security, performance, tests) in parallel |
| Debugging | Teammates test competing hypotheses and challenge each other's findings |
| Cross-Layer Coordination | Frontend, backend, and test changes each owned by a different teammate |
Agent Teams vs Subagents
| Aspect | Subagents | Agent Teams |
|---|---|---|
| Context | Own window; results return to caller | Own window; fully independent |
| Communication | Report back to main agent only | Teammates message each other directly |
| Coordination | Main agent manages all work | Shared task list with self-coordination |
| Best for | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
| Token cost | Lower (results summarized back) | Higher (each teammate is a separate instance) |
Rule of thumb: Use subagents for quick, focused workers. Use agent teams when teammates need to share findings, challenge each other, and coordinate independently.
Prerequisites
Agent teams are experimental and must be enabled:
// settings.json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Quick Start
Tell Claude to create a team using natural language:
Create an agent team with 3 teammates to [describe your task]. Have one teammate focus on [aspect 1], one on [aspect 2], and one on [aspect 3].
Claude creates the team, spawns teammates, assigns tasks, and coordinates work based on your prompt.
Available Skills
| Skill | Purpose | Example Triggers |
|---|---|---|
| team-blueprints | Pre-designed team configurations for 4 development phases | "research team", "feature team", "review team", "debug team" |
| team-coordination | Task management, messaging, plan approval, shutdown | "manage tasks", "team communication", "delegate mode" |
Available Commands
| Command | Description |
|---|---|
/agent-teams | Plugin overview and quickstart |
/spawn-research-team | Spawn a research & discovery team |
/spawn-feature-team | Spawn a feature development team |
/spawn-review-team | Spawn a code review & QA team |
/spawn-debug-team | Spawn a debugging & investigation team |
Team Architecture
An agent team consists of:
| Component | Role |
|---|---|
| Team Lead | The main Claude Code session that creates the team, spawns teammates, and coordinates |
| Teammates | Separate Claude Code instances that each work on assigned tasks |
| Task List | Shared list of work items that teammates claim and complete |
| Mailbox | Messaging system for direct communication between agents |
Teams and tasks are stored locally:
- •Team config:
~/.claude/teams/{team-name}/config.json - •Task list:
~/.claude/tasks/{team-name}/
Best Practices
- •Give teammates enough context — They load CLAUDE.md but don't inherit the lead's conversation history. Include task-specific details in spawn prompts.
- •Size tasks appropriately — Not too small (coordination overhead), not too large (long without check-ins). Self-contained units with clear deliverables.
- •Avoid file conflicts — Break work so each teammate owns different files.
- •Monitor and steer — Check progress, redirect approaches, synthesize findings.
- •Start with research — If new to teams, start with review/research tasks before parallel implementation.
Reference Documentation
For complete API documentation, tool descriptions, and detailed patterns, see:
${CLAUDE_PLUGIN_ROOT}/skills/agent-teams/references/agent-teams-reference.md