Mastering Claude Code Agent Teams: A Complete Guide to Parallel Multi‑Agent Collaboration

Claude Code Agent Teams Overview

Agent Teams is an experimental feature that lets multiple Claude instances collaborate on the same project. Each teammate runs in its own context, can exchange messages directly with other teammates, and the Team Lead coordinates work, assigns tasks, and aggregates results.

Core Components

Team Lead : The primary session that creates teammates, distributes tasks, and aggregates outcomes. It can be set to coordination‑only mode.

Teammates : Independent agents that execute assigned tasks. On creation they load the project context ( CLAUDE.md, MCP services, enabled skills) and any startup prompt supplied by the Lead. The Lead’s conversation history is not shared.

Task List : A shared list where each task has a state pending, in progress or completed. Tasks may declare dependencies; a dependent task cannot be claimed until its prerequisites are finished.

Mailbox : Instant messaging between agents. Messages can be addressed to a specific teammate or broadcast to all without polling.

Task Management Mechanics

The system automatically resolves dependencies. When a teammate finishes a task, any blocked tasks become unlocked. The Lead may assign tasks explicitly or allow any teammate to claim an unassigned task whose dependencies are satisfied. Claiming uses a file‑lock to avoid race conditions.

Configuration and task data are stored locally:

Team configuration : ~/.claude/teams/{team-name}/config.json Task list : ~/.claude/tasks/{team-name}/ The members array in the config records each teammate’s name, Agent ID, and type, enabling discovery.

Communication Model

Automatic delivery : Messages are delivered instantly to the target teammate.

Idle notification : When a teammate becomes idle after completing a task, the Lead is notified.

Shared task list : All agents can view and claim executable tasks.

Message types:

message : Send to a specific teammate.

broadcast : Send to all teammates (cost grows with team size, so use sparingly).

Agent Teams vs. Subagents

Context : Both run in independent windows; Subagents report results back to a single parent, while Agent Teams teammates operate autonomously.

Communication : Subagents only report to the main agent; Agent Teams teammates can talk to each other directly.

Coordination : Subagents are centrally managed; Agent Teams use a shared task list for self‑coordination.

Use case : Subagents suit quick, well‑defined tasks. Agent Teams excel at complex work that benefits from discussion and parallel exploration.

Token cost : Subagents are cheaper; each Agent Teams teammate is a full Claude instance, increasing token consumption linearly.

Quick Setup Guide

Prerequisites

Claude Code version ≥ 2.1.33 installed.

Access to ~/.claude/settings.json.

(Optional) tmux or iTerm2 for split‑pane mode.

Update Claude if needed:

claude update
claude --version

Step 1 – Enable the experimental flag

Edit ~/.claude/settings.json and add (or merge) the following block:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Restart Claude for the change to take effect.

Step 2 – Choose a display mode

In‑process : All teammates share a single terminal; you switch between them with keyboard shortcuts.

Split‑pane (tmux) : Each teammate gets its own pane, visible simultaneously. Requires tmux or iTerm2.

The default auto mode detects tmux and selects split‑pane; otherwise it falls back to in‑process. To force a mode, add to settings.json:

{
  "env": {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"},
  "teammateMode": "in-process"
}

or

{
  "teammateMode": "tmux"
}

Or override per session:

claude --teammate-mode in-process
claude --teammate-mode tmux

Step 3 – Install tmux (if using split‑pane)

macOS: brew install tmux Ubuntu/Debian/WSL: sudo apt update && sudo apt install tmux Verify installation:

which tmux
tmux -V

Step 4 – Verify activation

After restart, run the /config command. The output list should contain an “Agent Teams” entry. If missing, double‑check that the env block is correctly placed and that CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to "1".

Step 5 – Create your first team

Describe the goal in Claude; the system will split the work automatically:

创建一个智能体团队来重构认证模块。
将工作分解为可以独立完成的并行任务。

Or specify teammates manually:

创建一个包含 3 个队友的团队：
- 一个重构登录流程
- 一个重构注册流程
- 一个为两者更新测试
每个队友使用 Sonnet 模型。

Claude generates the teammates, assigns initial tasks, and starts collaborative execution.

Navigation & Interaction

In‑process shortcuts: Shift+Up / Shift+Down: Cycle the selected teammate. Enter: Focus the selected teammate’s view. Escape: Return to the Lead view or abort a running operation. Ctrl+T: Toggle the task list panel.

Type a message and press Enter to send to the highlighted teammate.

In split‑pane mode you click the pane of the teammate you wish to interact with and type commands directly.

Advanced Control Techniques

Delegate Mode : Press Shift+Tab after the team starts to make the Lead schedule work only, while teammates perform all execution.

Require Plan Approval : For high‑risk tasks, teammates must submit a plan before making changes. The Lead can approve (allow execution) or reject (force revision). Example prompt:

生成一个架构师队友来重构数据库架构。
在它们进行任何更改之前要求计划批准。

Specify Agent Models : Assign different Claude models per teammate to match task complexity. Example:

创建一个包含 4 个队友的团队：
- 使用 Haiku 的研究员（快速信息检索）
- 使用 Opus 的架构师（复杂设计决策）
- 两个使用 Sonnet 的实现者（代码更改）

Pre‑Approve Permissions : Run /permissions before starting a team to whitelist common file operations or commands. To skip permission checks entirely (use with caution): claude --dangerously-skip-permissions Close Teammates : Ask the Lead to shut down a teammate, e.g.: 请关闭队友 researcher Clean Up Team : After all work is done, issue the clean‑up command so the Lead removes shared resources only when no active teammates remain:

清理团队

Practical Scenarios

Scenario 1 – Parallel Code Review

Split a pull‑request review into three specialized agents:

创建一个智能体团队来审查 PR #142，生成三个审查员：
- 安全专家：检查漏洞、注入风险、认证缺陷
- 性能分析师：查找瓶颈、N+1 查询、内存问题
- 测试验证者：检查边缘情况和测试覆盖率
让它们独立完成审查，然后将结果整合成按优先级排序的问题列表。

Scenario 2 – Adversarial Debugging

When the root cause of an intermittent 500 error is unknown, spawn five agents each exploring a different hypothesis. They challenge each other's conclusions, and the surviving hypothesis is most likely correct.

用户报告结账端点间歇性 500 错误，大约 5% 的请求失败，没有明显规律。
创建 5 个队友智能体来调查不同可能原因：
1. 数据库连接池在高负载下耗尽
2. 库存预留中的竞态条件
3. 第三方支付 API 超时处理
4. 内存压力导致垃圾回收暂停
5. 服务间网络问题
让队友相互挑战、反驳彼此的理论。
最终能存活的假设最可能指向根本原因。

Scenario 3 – Cross‑Layer Feature Development

Develop a notification system by assigning each layer to a dedicated teammate:

创建一个智能体团队来开发通知系统：
- 队友 1：后端 API（创建、列表、标记已读）
- 队友 2：数据库表结构和迁移
- 队友 3：前端 React 组件（通知铃铛、下拉菜单、列表）
- 队友 4：实时更新的 WebSocket 集成
- 队友 5：端到端集成测试
每个队友只修改自己负责的文件。
通过共享任务列表进行协调。
需要依赖他人结果时，明确标记任务依赖。

Best Practices & Considerations

When to Use Agent Teams

Tasks that benefit from parallel exploration (research, multi‑module development, code review).

Work that can be divided into relatively independent units.

Situations requiring direct discussion and alignment among agents.

Avoid for strictly sequential tasks or when many agents need to edit the same file.

High inter‑dependency leading to frequent waiting diminishes benefits.

Very small routine tasks may incur more coordination overhead than value.

Token Cost Considerations

Each teammate is a separate Claude instance, so token usage grows linearly with the number of active teammates. Parallel exploration often justifies the cost, but simple single‑agent workflows are cheaper.

Current Limitations (Experimental)

No session resume: /resume and /rewind do not restore in‑process teammates.

Task state may lag: teammates sometimes delay marking a task as completed.

Close delay: teammates finish their current request before exiting.

One team per Lead: a Lead can manage only one team at a time.

No nested teams: teammates cannot create sub‑teams.

Terminal dependency: split‑pane mode requires tmux or iTerm2; otherwise the default is in‑process.

Practical Tips

Start with research or review tasks that have clear boundaries and do not modify code.

For cross‑layer development, assign distinct modules (backend, database, frontend, real‑time, tests) to different teammates.

Keep task granularity balanced – not too tiny (high coordination cost) nor too large (long periods without feedback).

Avoid having multiple teammates edit the same file; give each a dedicated file or module.

Monitor progress regularly and adjust strategy; idle teams waste tokens.

Conclusion

Claude Code Agent Teams provides a declarative, multi‑agent orchestration mechanism within the Claude ecosystem. While still experimental, it enables parallel AI workflows, adversarial validation, and modular development, extending beyond software engineering to any complex, multi‑facet project such as research, analysis, content creation, or planning.