Key Takeaway
- Agent Teams let you coordinate multiple Claude Code instances working in parallel, each with its own context window
- A team lead orchestrates the work — spawning teammates, assigning tasks, and synthesizing results
- Teammates can message each other directly, not just report back to the lead (unlike subagents)
- A shared task list with dependency management keeps everyone coordinated without manual tracking
- The feature is experimental and disabled by default — enable it via a settings flag
What Are Agent Teams?
Agent Teams are a new way to parallelize complex development work in Claude Code. Instead of a single session doing everything sequentially, you create a team: one Claude Code instance acts as the team lead, coordinating the effort, while multiple teammates — each a full, independent Claude Code session — work on their assigned pieces simultaneously.
The key difference from Claude Code's existing subagent system is communication. Subagents report results back to the main session and then disappear. Teammates are persistent, independent sessions that can talk to each other, challenge each other's findings, and self-coordinate through a shared task list. This makes Agent Teams suited for work where parallel collaboration matters — not just parallel execution.
Think of it like the difference between delegating subtasks to assistants who report back to you (subagents) versus running a real team standup where everyone can discuss, debate, and build on each other's work (Agent Teams).
How It Compares to Subagents
| Subagents | Agent Teams | |
|---|---|---|
| Context | Own context window; results return to the caller | Own context window; fully independent sessions |
| Communication | Report results back to the 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 to main context | Higher — each teammate is a separate Claude instance |
| Persistence | Temporary — gone after returning results | Persistent — runs until shut down or task is complete |
When to use subagents: Quick, focused work — researching a library, running a verification check, or any task where you only care about the final result.
When to use Agent Teams: Complex multi-faceted work — parallel code review with different lenses, debugging with competing hypotheses, building a feature across frontend/backend/tests simultaneously.
Key Features
Display Modes
Agent Teams support two display modes:
- In-process (default) — All teammates run inside your main terminal. Navigate between them with
Shift+Up/Downto select a teammate, then type to message them directly. Works in any terminal with no extra setup. - Split panes — Each teammate gets its own pane so you can see everyone's output simultaneously. Requires
tmuxor iTerm2 with theit2CLI.
The default is "auto" — it uses split panes if you're already in a tmux session, otherwise falls back to in-process. You can override this in settings or per-session with claude --teammate-mode in-process.
Plan Approval for Teammates
For high-stakes tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead reviews and approves their approach:
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
If the lead rejects the plan, the teammate revises based on feedback and resubmits. You can influence approval criteria through your prompt — e.g., "only approve plans that include test coverage."
Delegate Mode
By default, the team lead might start implementing tasks itself instead of waiting for teammates. Delegate mode restricts the lead to coordination-only tools — spawning, messaging, shutting down teammates, and managing tasks — so it stays focused on orchestration.
Enable it by pressing Shift+Tab after starting a team.
Direct Messaging Between Teammates
Each teammate is a full Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach:
- In-process mode:
Shift+Up/Downto select a teammate, then type your message - Split-pane mode: Click into a teammate's pane to interact directly
Teammates can also message each other, which is what enables the "scientific debate" pattern — where multiple agents actively try to disprove each other's theories to converge on the strongest answer.
Shared Task List with Dependencies
The shared task list is the coordination backbone of Agent Teams. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks — a pending task with unresolved dependencies stays blocked until those dependencies complete.
The lead can assign tasks explicitly, or teammates can self-claim: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own. Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task.
Quality Gates via Hooks
Claude Code's hook system integrates with Agent Teams through two events:
TeammateIdle— Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.TaskCompleted— Runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.
This lets you enforce quality standards automatically — run linting checks when a teammate finishes, verify test coverage before a task can be marked done, or ensure code review criteria are met.
Getting Started
Enable the experimental flag
Agent Teams are disabled by default. Add the flag to your settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Describe your team in natural language
Tell Claude what you need. Be specific about roles and the task:
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
Claude creates the team, spawns teammates, and coordinates work based on your prompt.
Choose a display mode
Set your preferred mode in settings.json:
{
"teammateMode": "in-process"
}Options are "auto" (default), "in-process", or "tmux". For a single session override: claude --teammate-mode in-process.
Monitor and steer
Check in on teammates' progress, redirect approaches that aren't working, and synthesize findings as they come in. Use Shift+Up/Down in in-process mode to navigate between teammates, or click panes in split mode. Press Ctrl+T to toggle the task list view.
Best Use Cases
Parallel code review with specialized lenses. A single reviewer tends to gravitate toward one type of issue. Splitting review criteria into independent domains ensures security, performance, and test coverage all get thorough attention simultaneously.
Create a team to review PR #142:
- Security reviewer: token handling, input validation, auth flows
- Performance reviewer: query optimization, memory usage, caching
- Test reviewer: coverage gaps, edge cases, flaky tests
Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three.
Investigating with competing hypotheses. When the root cause is unclear, a single agent tends to find one plausible explanation and stop. Agent Teams fight this by making teammates explicitly adversarial — each one investigates their own theory while trying to disprove the others'.
Users report the app exits after one message. Spawn 4 teammates
to investigate different hypotheses. Have them debate each
other's findings and converge on the actual root cause.
The debate structure prevents anchoring bias — the theory that survives cross-examination is far more likely to be correct.
Building independent modules in parallel. When a feature can be split into self-contained pieces that don't touch the same files, teammates can each own a separate piece without merge conflicts.
Create a team with 4 teammates to build the notification system:
- Backend API endpoints
- Database schema and migrations
- Frontend notification components
- Integration tests
The key is sizing tasks so each teammate owns distinct files. Two teammates editing the same file leads to overwrites.
Changes that span the full stack. Frontend, backend, and tests each owned by a different teammate, coordinated through the shared task list with dependencies.
Create a team for the user settings feature:
- Backend teammate: API routes and validation
- Frontend teammate: settings UI components (blocked by backend)
- Test teammate: E2E tests (blocked by both)
Task dependencies ensure the frontend teammate doesn't start until the API is ready, and the test teammate waits for both.
Architecture Overview
An Agent Team consists of four components:
| Component | Role |
|---|---|
| Team lead | The main Claude Code session that creates the team, spawns teammates, and coordinates work |
| Teammates | Separate Claude Code instances, each working on assigned tasks independently |
| Task list | Shared list of work items with status tracking and dependency management |
| Mailbox | Messaging system for direct communication between any agents |
Teams and tasks are stored locally on your machine:
- Team config:
~/.claude/teams/{team-name}/config.json - Task list:
~/.claude/tasks/{team-name}/
When spawned, teammates load the same project context as a regular session — CLAUDE.md, MCP servers, and skills — plus the spawn prompt from the lead. The lead's conversation history does not carry over, so include all task-specific details in the spawn prompt.
Messages are delivered automatically between agents. The lead doesn't need to poll for updates — when teammates send messages or go idle, the lead is notified automatically. The system also manages task dependencies: when a teammate completes a task that others depend on, blocked tasks unblock without manual intervention.
Experimental Limitations
Agent Teams are experimental. Key limitations to be aware of:
- No session resumption —
/resumeand/rewinddon't restore in-process teammates. After resuming, the lead may try to message teammates that no longer exist. - Task status can lag — Teammates sometimes fail to mark tasks as completed, blocking dependent tasks. Check manually if things seem stuck.
- One team per session — Clean up the current team before starting a new one.
- No nested teams — Teammates cannot spawn their own teams. Only the lead manages the team.
- Lead is fixed — You can't promote a teammate to lead or transfer leadership.
- Split panes limited — Split-pane mode requires tmux or iTerm2. Not supported in VS Code terminal, Windows Terminal, or Ghostty.
- Higher token cost — Each teammate is a separate Claude instance with its own context window. Token usage scales with team size.
DecodifAI Perspective
Agent Teams are impressive for large-scale development work — parallel code reviews, multi-hypothesis debugging, and full-stack feature builds are genuinely faster with this approach.
For most MKB projects, though, you probably don't need this yet. If your task can be handled sequentially or with simple subagents, that's cheaper and less complex to manage. Agent Teams shine when you're working on a codebase large enough that parallel exploration saves real time — think 10+ file changes across multiple layers.
Our recommendation: start with subagents for research and verification tasks. Graduate to Agent Teams when you find yourself wishing your AI assistant could "split into three and work on this from different angles."