$ man how-to/agent-teams-claude-code

Agent Teams are Claude Code sessions that can talk to each other. The earlier parallel agent entries in this guide cover subagents, which are fire-and-forget. You launch a subagent, it does its task, it reports back to the parent. That is it. No communication between subagents. No shared task tracking. No coordination beyond what the parent orchestrates. Agent Teams add three things subagents do not have. First, a shared task list that every teammate can read and update. Second, direct messaging between agents, not just parent-to-child but peer-to-peer. Third, lifecycle management so the team lead can spawn, assign, monitor, and shut down teammates from a single session. The practical difference: subagents are good for independent parallel tasks where no agent needs to know what another agent is doing. Teams are good for coordinated parallel tasks where agents need to hand off context, check each other's work, or adapt based on what a teammate discovered. If you have ever managed a small team of people, the mental model is identical. You assign tasks, people work in parallel, they message you with questions, you review output, and you decide when the work is done.

CODE

Agent Teams are experimental as of February 2026. Enable them by adding the environment variable to your Claude Code settings: In ~/.claude/settings.json: { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } Restart Claude Code after adding this. The feature will not activate until the next session. Once enabled, you can ask Claude to create a team naturally or it happens through the TeamCreate tool. A team gets a name, a description, and a config file at ~/.claude/teams/{team-name}/config.json. The config tracks team members with their names, agent IDs, and roles. Each team gets a corresponding task list at ~/.claude/tasks/{team-name}/. This is the shared work tracker that every teammate can read and write to. Display modes matter. The default is in-process, where all teammates run in the main terminal and you use Shift+Down to cycle between them. If you have tmux or iTerm2, set "teammateMode": "tmux" in settings.json and each teammate gets its own split pane. The pane view makes it easier to monitor parallel work. You can also pass --teammate-mode on the command line for one-off sessions.

PATTERN

Tasks are the coordination backbone. Every piece of work gets a task with a subject, description, status (pending, in_progress, completed), and optional dependencies. Dependencies are the key feature. Task 4 can be blocked by tasks 2 and 3. That means no one picks up task 4 until both 2 and 3 are done. This enforces wave discipline automatically. You do not need to babysit the sequencing. The task list enforces it. The workflow: the team lead creates tasks, sets dependencies, and assigns owners. Teammates check the task list after completing each piece of work to find what is available next. They claim unblocked tasks, work them, mark them complete, and check for the next one. Tip: prefer assigning tasks in ID order (lowest first) when multiple are available. Earlier tasks often set up context that later tasks depend on. This is the same wave pattern from the parallel agents guide, just formalized into a task system instead of manual orchestration.

PATTERN

Teammates communicate through SendMessage. Three message types exist. Direct messages go to one specific teammate by name. The researcher sends findings to the team lead. The writer asks the reviewer a question. These are the most common and cheapest messages. Broadcasts go to every teammate at once. Use these sparingly because each broadcast sends a separate message to every agent, which means N teammates equals N API calls. Valid use: a critical blocker that affects everyone. Invalid use: a status update that only the lead cares about. Shutdown requests tell a teammate to wrap up and exit. The teammate can approve (and terminate) or reject with a reason. This is how you cleanly end a team session without killing processes. Messages are delivered automatically. You do not need to poll an inbox. When a teammate sends a message, it arrives in your conversation as a new turn. If you are busy mid-turn, messages queue and deliver when your turn ends.

PRO TIP

The agents are not the breakthrough. The management layer is. Without constraints, parallel agents create chaos. Two agents edit the same file and the last write wins silently. An agent makes an architectural decision that conflicts with another agent's assumption. A deploy goes out before all agents finish. The management layer is a constraints file that every teammate reads before making any change. My TEAM-CONSTRAINTS.md enforces six rules: 1. File ownership. One writer per file per wave. No two agents touch the same file simultaneously. 2. Decision logging. When an agent makes a choice (naming convention, import path, data structure), it messages the team lead with a [DECISION] prefix. That decision becomes available to all teammates. 3. Read before write. Every agent reads an existing example of whatever it is about to create. The existing code IS the style guide. 4. Wave discipline. Foundation tasks first, consumers second, integration third, validation last. No skipping ahead. 5. Build gate. No deploy until the build passes clean and the team lead confirms. 6. Context before action. Every teammate gets the constraints file, a specific task description, file references, and ownership boundaries. If any are missing, the agent asks before proceeding. You do not need my exact constraints file. You need A constraints file. The specific rules matter less than having rules at all. Without them, agents drift. With them, agents coordinate.

FORMULA

Use subagents (the Task tool) when tasks are fully independent. No agent needs output from another agent. No agent needs to check another agent's work. Each task has a clear input and clear output with no cross-dependencies. Example: three agents each writing a separate wiki page that does not reference the others. Use teams when tasks are coordinated. Agents need to hand off context. One agent's output feeds another agent's input. Someone needs to review before the next step starts. Example: a researcher gathers data, a writer turns it into content, a reviewer checks voice compliance, and a deploy agent pushes the result. The cost difference matters. Teams use roughly 7x more tokens than a single session because each teammate runs its own context window. Keep teams small (2 to 4 agents), keep tasks focused, and clean up when done. Do not spin up a team for a task that one focused agent can handle. Current limitations to know: one team per session, no nested teams (teammates cannot spawn their own teams), the lead role is fixed (cannot transfer leadership mid-session), and session resumption does not work with in-process teammates. These are experimental constraints that will likely improve. The decision framework: if you can describe the task in one prompt and the agent can finish without asking anyone a question, use a subagent. If the task involves handoffs, reviews, or multi-step coordination, use a team.