Claude Code Agent Teams represent an experimental, advanced capability for orchestrating multiple, independent Claude Code instances to collaboratively solve complex problems. This methodology enables parallelization of tasks, inter-agent messaging, and centralized management by a designated team lead.

The core methodology revolves around a decentralized yet coordinated architecture comprising:

1. Team Lead: The primary Claude Code session, responsible for creating the team, spawning teammates, coordinating work, assigning tasks, and synthesizing results.
2. Teammates: Individual, fully independent Claude Code instances, each operating within its own isolated context window, capable of direct communication with other teammates.
3. Shared Task List: A centralized repository of work items (tasks) accessible to all team members. Tasks possess states (pending, in-progress, completed) and can have dependencies, ensuring sequential execution where necessary. Task claiming employs file locking mechanisms to prevent race conditions during concurrent attempts to acquire tasks.
4. Mailbox System: An inter-agent communication framework facilitating direct messaging between teammates (message to a specific agent, broadcast to all) and automatic delivery of messages and idle notifications (when a teammate finishes and stops).

Upon initiation, which can be user-requested or Claude-proposed based on task complexity, the lead agent configures the team structure. Teammates are spawned with their own context window, loading project context (e.g., CLAUDE.md, MCP servers, skills) but not inheriting the lead's conversation history. Permissions are initially inherited from the lead, though individual teammate permissions can be adjusted post-spawn.

Operational control allows for various interaction paradigms:

• Display Modes: in-process (all teammates within the main terminal, navigated via Shift+Up/Down) or split-pane (each teammate in a dedicated pane, requiring tmux or iTerm2).
• Task Assignment and Delegation: The lead can explicitly assign tasks, or teammates can self-claim available, unblocked tasks. A delegate mode restricts the lead to coordination-only tools, preventing it from directly implementing solutions.
• Plan Approval: For critical tasks, teammates can be required to operate in a read-only plan mode, submitting their approach for lead approval before proceeding to implementation.
• Direct Interaction: Users can directly message any teammate, bypassing the lead, to provide specific instructions or redirect their approach.

Agent Teams are particularly effective for tasks benefiting from concurrent, independent exploration, such as:

• Research and Review: Multiple perspectives (e.g., security, performance, test coverage) simultaneously reviewing a codebase.
• Modular Development: Teammates owning distinct, independent modules or features.
• Debugging with Competing Hypotheses: Parallel investigation and adversarial validation of different root cause theories.
• Cross-Layer Coordination: Simultaneous changes across frontend, backend, and testing layers.

They contrast with subagents, which operate within a single session, report only to the main agent, and are best for focused tasks where only the result matters. Agent Teams, conversely, facilitate complex collaboration where inter-agent discussion and self-coordination are crucial, albeit at a significantly higher token cost due to each teammate functioning as a separate Claude instance.

Limitations include experimental status, lack of session resumption for in-process teammates, potential task status lag, and the restriction of one team per session without nested teams. Best practices emphasize providing sufficient context, appropriate task sizing, monitoring, and avoiding file conflicts to maximize efficiency and prevent wasted effort.