Mastering Parallel Tasks with Claude Code Agent Teams: Best Practices

Agent Teams vs. Subagents

Claude Code originally used Subagents (or git worktrees) for parallel tasks; Subagents report only to the main agent and cannot communicate directly. Agent Teams remove this limitation, allowing teammates to exchange messages.

Communication : Subagents only report to the main agent; Agent Teams enable direct peer‑to‑peer messaging.

Coordination : Subagents are centrally managed; Agent Teams share a task list and self‑coordinate.

Context : Subagents have separate context windows but results are aggregated to the main session; Agent Teams give each teammate a fully independent window.

Token cost : Subagents are cheaper (result aggregation); Agent Teams are more expensive because each teammate runs its own Claude instance.

Suitable scenarios : Subagents excel at result‑oriented, focused tasks; Agent Teams shine for complex work that requires discussion, questioning, and collaborative reasoning.

When to Enable Agent Teams

Agent Teams are not suitable for every task because they increase token consumption (a three‑person team can cost 3‑4× a single session). Official documentation lists strong use cases:

Research and review tasks – multiple teammates investigate different aspects (e.g., security, performance, test coverage) and share findings.

New module or feature development – each teammate works on an independent part without file conflicts.

Bug debugging with competing hypotheses – teammates run parallel experiments to converge on the root cause faster.

Cross‑layer coordination – front‑end, back‑end, and test changes can proceed simultaneously.

Unsuitable scenarios include strongly sequential dependencies, multiple people editing the same file, or highly inter‑dependent tasks; in those cases a single session or Subagents are preferable.

How to Enable Agent Teams

Agent Teams are not enabled by default. Two prerequisites are required:

Claude Code version ≥ v2.1.32 (Native installation updates automatically).

Add the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1" to ~/.claude/settings.json.

Start a team by describing the desired team and task in natural language; Claude creates a team lead, generates teammates, and coordinates the work.

I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

Key prompt words ( agent team, teammate, team lead) are required; otherwise Claude may fall back to Subagents.

Controlling Teammates

Agent Teams support two display modes:

In‑process : All teammates run in the main terminal; switch with Shift+Down.

Split panes : Each teammate gets its own pane (requires tmux or iTerm2).

Configuration options (global ~/.claude.json or command‑line flag) let you choose the mode:

{
  "teammateMode": "tmux"
}

Launch flags: claude --teammate-mode tmux During execution you can send messages directly to a teammate using Shift+Down to focus, then Enter to send, Escape to abort the current round, or Ctrl+T to view the shared task list.

The shared task list tracks three states (pending, in progress, completed) and can express dependencies (blocked tasks).

Assignment can be explicit ( Assign this task to the researcher teammate) or automatic (teammates claim the next unassigned task after finishing).

For high‑risk tasks you can require a planning step approved by the lead before execution:

Spawn an architect teammate to add structured logging middleware. Require plan approval before any changes. Reject any plan that does not include rollback strategy and test coverage.

Hooks ( TeammateIdle, TaskCreated, TaskCompleted) allow you to enforce hard constraints; exiting with code 2 aborts the corresponding action.

Two Practical Play‑throughs

Example 1: One‑sentence research team

Enable Agent Teams to research the core differences and relationships among MCP, Skills, Plugins, Hooks, and Agent Teams in Claude Code.

Claude creates a team lead plus five teammates, each exploring a different angle, and the lead synthesizes the final output.

Example 2: tmux split‑pane experience

Repeat the above workflow inside a tmux session to see automatic pane creation for each teammate.

Best Practices for Parallel Work

Provide sufficient context : Include file paths, module conventions, and tech‑stack details in the prompt; teammates do not inherit the lead’s conversation history.

Team size 3‑5 : Larger teams increase coordination overhead and token cost; 3‑5 teammates handling 5‑6 tasks is a proven sweet spot.

Appropriate task granularity : Tasks should be self‑contained deliverables (a function, a test file, a review) – not too tiny to cause overhead, nor too large to stall teammates.

Wait for teammates : Instruct the lead to wait for teammates to finish before proceeding (e.g., "wait for your teammates to complete their tasks before proceeding").

Start with research/review tasks : New users should begin with non‑coding tasks (PR review, library research, bug investigation) to see value without coordination complexity.

Avoid file conflicts : Ensure each teammate works on distinct files to prevent overwrites.

Active monitoring : Use Ctrl+T to inspect the task list and Shift+Down to redirect a teammate if the direction drifts.

Troubleshooting team launch failures : Verify the prompt contains the keywords agent team / teammate, confirm the environment variable is set to 1, restart Claude Code after editing settings.json, and check ~/.claude/teams/ for a newly created team directory.

Agent Teams are an engineering‑level implementation of multi‑agent collaboration in Claude Code, optimized for small, transparent teams that run locally without cloud dependencies. For massive parallelism (hundreds of sub‑agents), consider alternatives such as Kimi K2.6 Agent Swarm.