Orchestrate teams of Claude Code sessions编排 Claude Code 会话团队

​

When to use agent teams何时使用智能体团队

• Research and review: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other’s findings研究与评审：多名成员可以同时调查问题的不同方面，然后分享并质疑彼此的发现。
• New modules or features: teammates can each own a separate piece without stepping on each other新模块或功能开发：成员可以各自负责独立的部分，互不干扰。
• Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster基于竞争性假设的调试：成员并行测试不同的理论，从而更快地收敛到正确答案。
• Cross-layer coordination: changes that span frontend, backend, and tests, each owned by a different teammate跨层协调：涉及前端、后端和测试的变更，由不同的成员分别负责。

​

Compare with subagents与子智能体对比

​

Enable agent teams启用智能体团队

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

​

Start your first agent team启动你的第一个智能体团队

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

• Up and down arrows: select a teammate向上和向下箭头：选择团队成员
• Enter: open the selected teammate’s transcript and message it directly回车键：打开所选成员的对话记录并直接发送消息
• Escape: clear the selection. While you’re viewing a teammate’s transcript, Escape interrupts that teammate’s current turnEsc 键：清除选择。当你正在查看成员的对话记录时，Esc 键会中断该成员当前的轮次

​

Control your agent team控制你的智能体团队

​

Choose a display mode选择显示模式

• In-process: all teammates run inside your main terminal. Use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view it and type to message it directly. Works in any terminal, no extra setup required.进程内 (In-process)：所有成员在你的主终端内运行。使用智能体面板中的上下箭头键选择成员，按回车键查看并输入消息直接与其对话。适用于任何终端，无需额外设置。
• Split panes: each teammate gets its own pane. You can see everyone’s output at once and click into a pane to interact directly. Requires tmux, or iTerm2.分割窗格 (Split panes)：每个成员拥有自己的窗格。你可以同时查看所有人的输出，并点击进入某个窗格进行直接交互。需要 tmux 或 iTerm2。

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• tmux: install through your system’s package manager. See the tmux wiki for platform-specific instructions.tmux：通过系统包管理器安装。请参阅 tmux wiki 获取特定平台的安装说明。
• iTerm2: install the it2 CLI, then enable the Python API in iTerm2 → Settings → General → Magic → Enable Python API.iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

​

Specify teammates and models指定成员和模型

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

1. The model your spawn prompt names for that teammate.你在生成提示词中为该成员指定的模型。
2. For a teammate spawned from a subagent definition, the definition’s model, where inherit selects the lead’s model.对于从子智能体定义生成的成员，使用该定义的模型（inherit 表示继承负责人的模型）。
3. CLAUDE_CODE_SUBAGENT_MODEL, when it’s set to anything other than inherit.当 CLAUDE_CODE_SUBAGENT_MODEL 设置为非 inherit 的值时，使用该值。
4. The lead’s current model.负责人的当前模型。

• Family alias such as opus: On the Anthropic API and Claude Platform on AWS, Claude Code runs the teammate on the newest version of that family the allowlist permits. On providers with provider-specific model IDs, where the substitution doesn’t operate, a blocked alias falls back like any other blocked value per the next bullet系列别名（如 opus）：在 Anthropic API 和 AWS 上的 Claude Platform 中，Claude Code 会在白名单允许的该系列最新版本上运行成员。在提供商特定模型 ID 的提供商处（不支持替换功能），被拦截的别名会按照下一点的规则回退。
• Any other blocked value, including a family alias on providers where the substitution doesn’t operate, or one whose family has no permitted version: Claude Code runs the teammate on the lead’s model instead. If you set CLAUDE_CODE_SUBAGENT_MODEL, Claude Code tries that model first, under these same rules任何其他被拦截的值，包括不支持替换功能的提供商处的系列别名，或其系列中没有允许版本的别名：Claude Code 会在负责人的模型上运行成员。如果你设置了 CLAUDE_CODE_SUBAGENT_MODEL，Claude Code 会根据这些规则优先尝试该模型。

​

Have teammates plan before implementing让成员在实施前进行规划

Spawn an architect teammate to refactor the authentication module.

​

Talk to teammates directly直接与成员对话

• In-process mode: use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view its session and type to send it a message. Press x on a selected teammate to stop it. Press Ctrl+T to toggle the task list.进程内模式：使用智能体面板中的上下箭头键选择成员，按回车键查看其会话并输入消息。在选定成员上按 x 可停止它。按 Ctrl+T 可切换任务列表。
• Split-pane mode: click into a teammate’s pane to interact with their session directly. Each teammate has a full view of their own terminal.分割窗格模式：点击进入成员的窗格以直接与其会话交互。每个成员都拥有其自身终端的完整视图。

​

Assign and claim tasks分配和认领任务

• Lead assigns: tell the lead which task to give to which teammate负责人分配：告诉负责人将哪个任务交给哪个成员。
• Self-claim: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own自行认领：成员完成任务后，会自动拾取下一个未分配且未被阻塞的任务。

​

Shut down teammates关闭成员

Ask the researcher teammate to shut down

​

Enforce quality gates with hooks使用钩子执行质量门禁

• TeammateIdle: runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.TeammateIdle：当成员即将进入空闲状态时运行。以代码 2 退出可发送反馈并让成员继续工作。
• TaskCreated: runs when a task is being created. Exit with code 2 to prevent creation and send feedback.TaskCreated：当任务被创建时运行。以代码 2 退出可阻止创建并发送反馈。
• TaskCompleted: runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.TaskCompleted：当任务被标记为完成时运行。以代码 2 退出可阻止完成并发送反馈。

​

How agent teams work智能体团队的工作原理

​

How Claude starts agent teamsClaude 如何启动智能体团队

​

Architecture架构

• Team config: ~/.claude/teams/{team-name}/config.json团队配置：~/.claude/teams/{team-name}/config.json
• Task list: ~/.claude/tasks/{team-name}/任务列表：~/.claude/tasks/{team-name}/

​

Use subagent definitions for teammates使用子智能体定义作为成员

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools: Claude Code limits the teammate to the tools in the definition’s tools list. For an in-process teammate, Claude Code adds SendMessage to that list, and in a session that has the Task tools it adds TaskCreate, TaskGet, TaskList, and TaskUpdate too.tools：Claude Code 将成员限制为定义中工具列表内的工具。对于进程内成员，Claude Code 会将 SendMessage 添加到该列表；若会话拥有任务工具，还会添加 TaskCreate、TaskGet、TaskList 和 TaskUpdate。
• model: Claude Code uses the definition’s model in either display mode when your spawn prompt doesn’t name one. See how Claude Code picks a teammate’s model.model：当你的生成提示词未命名模型时，Claude Code 在任一显示模式下都会使用定义的模型。请参阅“Claude Code 如何选择成员模型”。
• Body: for an in-process teammate, Claude Code appends the definition’s body to its default system prompt as additional instructions. For a split-pane teammate, Claude Code uses the body in place of its default system prompt.Body：对于进程内成员，Claude Code 会将定义的 Body 附加到其默认系统提示词中作为额外说明。对于分割窗格成员，Claude Code 使用该 Body 替代其默认系统提示词。
• skills: Claude Code doesn’t apply the definition’s skills to a teammate in either display mode. The teammate loads skills from your project and user settings.skills：Claude Code 不会在任一显示模式下将定义的技能应用于成员。成员会从你的项目和用户设置中加载技能。
• mcpServers: for a split-pane teammate, Claude Code applies the definition’s mcpServers under the rules for that field, which cover a session started with --agent as well. An in-process teammate ignores the field and loads MCP servers from your project and user settings.mcpServers：对于分割窗格成员，Claude Code 根据该字段的规则应用定义的 mcpServers（同样涵盖使用 --agent 启动的会话）。进程内成员会忽略该字段并从你的项目和用户设置中加载 MCP 服务器。

​

Permissions权限

​

Messages between agents智能体间的消息

• It treats an approval claim relayed from another agent as untrusted input rather than confirmation from you.它将从另一个智能体转达的批准声明视为不可信输入，而非来自你的确认。
• It reviews each message before Claude Code delivers it, whether a plain message or a structured protocol message such as a shutdown request or plan approval response. A message it blocks never reaches the recipient.它会在 Claude Code 投递消息前审查每条消息，无论是纯文本消息还是结构化协议消息（如关闭请求或计划批准响应）。被拦截的消息永远不会到达接收方。

​

Context and communication上下文与通信

• Automatic message delivery: when teammates send messages, they’re delivered automatically to recipients. The lead doesn’t need to poll for updates.自动消息投递：当成员发送消息时，它们会自动投递给接收者。负责人无需轮询更新。
• Idle notifications: when a teammate finishes and stops, it automatically notifies the lead and includes its final answer in the notification. A teammate whose turn ends on an API error notifies the lead that it failed and includes the error text.空闲通知：当成员完成工作并停止时，它会自动通知负责人并在通知中包含其最终答案。轮次因 API 错误而结束的成员会通知负责人其失败并包含错误文本。
• Shared task list: agents that have the Task tools can see task status and claim available work.共享任务列表：拥有任务工具的智能体可以查看任务状态并认领可用工作。
• Teammate messaging: send a message to one specific teammate by name. To reach everyone, send one message per recipient.成员消息：按名称向特定成员发送消息。若要联系所有人，请为每个接收者发送一条消息。

​

Token usageToken 使用量

​

Use case examples用例示例

​

Run a parallel code review运行并行代码评审

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

Investigate with competing hypotheses基于竞争性假设的调查

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

​

Best practices最佳实践

​

Give teammates enough context给予成员足够的上下文

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

​

Choose an appropriate team size选择合适的团队规模

• Token costs scale linearly: each teammate has its own context window and consumes tokens independently. See agent team token costs for details.Token 成本线性扩展：每个成员都有自己的上下文窗口并独立消耗 Token。详情请参阅“智能体团队 Token 成本”。
• Coordination overhead increases: more teammates means more communication, task coordination, and potential for conflicts协调开销增加：成员越多，意味着更多的通信、任务协调和潜在冲突。
• Diminishing returns: beyond a certain point, additional teammates don’t speed up work proportionally边际效应递减：超过一定点后，增加成员不会按比例加快工作速度。

​

Size tasks appropriately合理拆分任务规模

• Too small: coordination overhead exceeds the benefit太小：协调开销超过收益。
• Too large: teammates work too long without check-ins, increasing risk of wasted effort太大：成员在没有核对的情况下工作时间过长，增加了浪费工作的风险。
• Just right: self-contained units that produce a clear deliverable, such as a function, a test file, or a review恰到好处：产生明确交付成果的自包含单元，例如函数、测试文件或评审。

​

Wait for teammates to finish等待成员完成

Wait for your teammates to complete their tasks before proceeding

​

Start with research and review从研究和评审开始

​

Avoid file conflicts避免文件冲突

​

Monitor and steer监控与引导

​

Troubleshooting故障排除

​

Teammates not appearing成员未出现

• In in-process mode, teammates appear in the agent panel below the prompt input. Use the up and down arrow keys to select one, then press Enter to view it.在进程内模式下，成员出现在提示输入下方的智能体面板中。使用上下箭头键选择一个，然后按回车键查看。
• A teammate row that disappeared after sitting idle has been hidden, not stopped. Idle rows hide 30 seconds after the whole panel goes idle and reappear on the teammate’s next turn. When more than three teammates are idle, their surplus rows collapse into a single N idle agents row that Enter expands. Send the teammate a message by name to bring a hidden row back.空闲后消失的成员行是被隐藏了，而不是停止了。空闲行会在整个面板空闲 30 秒后隐藏，并在成员下一轮次时重新出现。当超过三个成员空闲时，多余的行会折叠成一行“N 个空闲智能体”，按回车键可展开。按名称向成员发送消息可使隐藏行重新出现。
• Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task.检查你给 Claude 的任务是否足够复杂以至于需要团队。Claude 根据任务决定是否生成成员。
• If you explicitly requested split panes, ensure tmux is installed and available in your PATH:
  which tmux
  
  如果你显式请求了分割窗格，请确保 tmux 已安装且在你的 PATH 中： which tmux
• For iTerm2, verify the it2 CLI is installed and the Python API is enabled in iTerm2 preferences.对于 iTerm2，请验证 it2 CLI 已安装，并且在 iTerm2 首选项中启用了 Python API。

​

Claude spawns teammates instead of subagentsClaude 生成团队成员而非子智能体

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• Higher-precedence settings files: project settings, local settings, and a --settings payload apply after user settings, so an env entry that sets the variable to 1 in any of them wins. See Settings precedence.优先级更高的设置文件（如项目设置、本地设置以及 --settings 载荷）会在用户设置之后应用，因此在其中任何一个文件中将该变量设置为 1 的环境变量条目都将生效。请参阅“设置优先级”。
• Managed settings: managed settings apply after every other source. If your organization enables agent teams there, ask your administrator to change the managed value.托管设置：托管设置会在所有其他来源之后应用。如果你的组织在此处启用了智能体团队，请联系管理员更改托管值。

​

Too many permission prompts权限提示过多

​

Agents stopping early智能体提前停止

• Give them additional instructions directly直接给予进一步指示
• Spawn a replacement teammate to continue the work生成一名新的团队成员来继续工作

​

Orphaned tmux sessions孤立的 tmux 会话

tmux ls
tmux kill-session -t <session-name>

​

Limitations限制

• No session resumption with in-process teammates: /resume and /rewind do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.进程内团队成员不支持会话恢复：/resume 和 /rewind 指令无法恢复进程内团队成员。恢复会话后，主智能体可能会尝试向已不存在的团队成员发送消息。如果发生这种情况，请指示主智能体生成新的团队成员。
• Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.任务状态可能滞后：团队成员有时无法将任务标记为已完成，这会阻塞后续任务。如果任务看起来卡住了，请检查工作是否实际已完成，并手动更新任务状态，或指示主智能体提醒该成员。
• Shutdown can be slow: teammates finish their current request or tool call before shutting down, which can take time.关闭过程可能较慢：团队成员在关闭前会完成当前的请求或工具调用，这可能需要一些时间。
• One team per session: a session has exactly one team, scoped to that session. You can’t create additional named teams or share a team across sessions.每个会话仅限一个团队：一个会话只能拥有一个团队，且作用域仅限于该会话。你无法创建额外的命名团队，也无法在不同会话间共享团队。
• No nested teams: teammates cannot spawn their own teammates. Only the lead can manage the team.不支持嵌套团队：团队成员无法生成自己的团队成员。只有主智能体可以管理团队。
• No background subagents from in-process teammates: an in-process teammate’s own subagents run in the foreground, because a teammate’s background work can’t outlive the lead’s process. Claude Code returns an error when a teammate spawns a subagent whose definition sets background: true. A teammate’s run_in_background: true request also fails, either with an error or by running silently in the foreground, as described in how Claude Code picks foreground or background. Subagents launched from the main conversation follow the background default.进程内团队成员不支持后台子智能体：进程内团队成员的子智能体会在前台运行，因为团队成员的后台工作无法在主智能体的进程结束后继续存在。当团队成员生成定义了 background: true 的子智能体时，Claude Code 会返回错误。团队成员发出的 run_in_background: true 请求也会失败，要么报错，要么在后台静默运行（具体取决于 Claude Code 如何选择前台或后台运行，详见相关说明）。从主会话启动的子智能体遵循后台默认设置。
• Lead is fixed: the main session is the lead for its lifetime. You can’t promote a teammate to lead or transfer leadership.主智能体固定不变：主会话在整个生命周期内始终担任主智能体。你无法将团队成员提升为主智能体，也无法转移领导权。
• Permissions set at spawn: teammates start with the permission mode described under Permissions. You can change an individual teammate’s permission mode after spawning, but you can’t set per-teammate permission modes at spawn time.权限在生成时设定：团队成员启动时遵循“权限”部分描述的权限模式。你可以在生成后更改单个团队成员的权限模式，但无法在生成时针对每个成员单独设置权限模式。
• Split panes require tmux or iTerm2: the default in-process mode works in any terminal. Split-pane mode isn’t supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.分屏窗格需要 tmux 或 iTerm2：默认的进程内模式可在任何终端中使用。VS Code 集成终端、Windows Terminal 或 Ghostty 不支持分屏模式。

​

Next steps后续步骤

• Lightweight delegation: subagents spawn helper agents for research or verification within your session, better for tasks that don’t need inter-agent coordination轻量级委派：子智能体在你的会话内生成辅助智能体进行研究或验证，这更适合不需要智能体间协调的任务。
• Messaging between your own sessions: cross-session messaging lets Claude pass findings between the sessions you run yourself跨会话消息传递：跨会话消息传递允许 Claude 在你自己运行的多个会话之间传递发现的信息。
• Manual parallel sessions: Git worktrees let you run multiple Claude Code sessions yourself without automated team coordination手动并行会话：Git 工作树（worktrees）允许你自己运行多个 Claude Code 会话，而无需自动化的团队协调。