协调器模式

Claude Code 有两种不同的多代理系统。协调器模式是星型模型，中央代理编排工作者。Team/Swarm 是对等网络，任何队友都可以向任何其他队友发送消息。

2 多代理拓扑 4 仅协调器工具 3 终端后端 1s 邮箱轮询间隔

i 两个不同的系统，不是一个

协调器模式通过环境变量激活，并将主模型限制为仅编排工具。 Team/Swarm 通过向 Agent 工具传递 team_name 激活，并使用 tmux 进行可视化布局和基于文件的邮箱进行消息传递。

拓扑

Coordinator Mode (hub-and-spoke)

Coordinator

(Agent, SendMessage, TaskStop only)

┌────┼────┐

Worker 1 Worker 2 Worker 3

(full tools) (full tools) (full tools)

Activated with CLAUDE_CODE_COORDINATOR_MODE=1. Coordinator cannot touch the filesystem directly.

Team/Swarm (peer-to-peer)

Team Lead Teammate A

<── SendMessage ──>

└────────┬────────┘

Teammate B

Activated by passing team_name to the Agent tool. Visualized in tmux split panes.

协调器模式

激活

Requires feature flag COORDINATOR_MODE enabled in the build, plus the environment variable:

CLAUDE_CODE_COORDINATOR_MODE=1

变化

Aspect	Normal mode	Coordinator mode
System prompt	Default Claude Code prompt	Coordinator-specific prompt
Available tools	All ~45 tools	Agent, SendMessage, TaskStop, SyntheticOutput only
File access	Direct (Read, Edit, Write)	Only through workers
Shell access	Direct (Bash)	Only through workers

4 阶段任务工作流

Phase	Who	Purpose
1. Research	Workers (parallel)	Investigate the codebase — run freely in parallel
2. Synthesis	Coordinator	Read findings, write specs with exact file paths and line numbers
3. Implementation	Workers (sequential per file set)	Make changes per spec — one worker at a time per file area
4. Verification	Workers	Test that it works — can run alongside impl in different file areas

工作者结果格式

Worker results arrive back as user-role messages with XML:

<task-notification>
  <task-id>agent-a1b2c3</task-id>
  <status>completed</status>  <!-- completed | failed | killed -->
  <summary>Brief summary of what happened</summary>
  <result>Detailed output from the worker</result>
  <usage>Token usage stats</usage>
</task-notification>

继续 vs 生成决策

Situation	Action	Reason
Research worker explored files that need editing	Continue (SendMessage)	Already has context loaded
Research was broad but implementation is narrow	Spawn fresh	Don't carry unnecessary context
Fixing a failure	Continue	Has error context
Verifying another worker's code	Spawn fresh	Fresh eyes, no bias
Previous approach was completely wrong	Spawn fresh	Clean slate

i 关键规则：工作者无法看到协调器的对话

每个工作者的提示词必须完全自包含。协调器必须综合发现并包含文件路径、行号和确切指令。绝不要写"根据你的发现" — 工作者无法访问先前的上下文。

Team/Swarm 系统

团队结构

Team config

~/.claude/teams/{team-name}/config.json

Task list

~/.claude/tasks/{team-name}/

Inboxes

~/.claude/teams/{team-name}/inboxes/{name}.json

Team lead name

"team-lead" (fixed)

团队工作流

Team lead creates team with TeamCreate

Create tasks with Task tools

Spawn teammates with Agent tool (team_name + name parameters)

Assign tasks with TaskUpdate (owner field)

Teammates work and mark tasks completed

Teammates communicate via SendMessage

Graceful shutdown: SendMessage with {type: "shutdown_request"}

Clean up with TeamDelete (only works when no teammates are active)

队友类型

In-process

Uses AsyncLocalStorage for isolated context within the same process. Used for testing and headless mode.

Tmux

Runs as a separate Claude Code process in a tmux pane. Each pane has a unique border color and title.

iTerm2

Alternative backend for iTerm2 on macOS, using AppleScript for tab/split management.

Tmux 布局

Inside existing tmux session

Splits the current window
Team lead: 30% left panel
Teammates: 70% right panel
Layout: main-vertical

Outside tmux

Creates new session: claude-swarm
Window name: swarm-view
Isolated socket: claude-swarm-{pid}
Layout: tiled

SendMessage 工具

Dual-purpose tool: continues existing workers in Coordinator Mode, and routes messages between teammates in Team/Swarm mode.

在协调器模式中

// Continue an existing worker by agent ID
SendMessage({
  to: "agent-a1b2c3",
  message: "Fix the bug in auth.ts:45 based on..."
})
// Worker resumes with full context preserved

在 Team/Swarm 模式中

// Direct message to a teammate
SendMessage({ to: "backend-dev", message: "..." })

// Broadcast to all teammates (use sparingly)
SendMessage({ to: "*", message: "All tests pass" })

消息路由逻辑

bridge:<id>

Remote session via REPL bridge

uds:<path>

Local peer via Unix Domain Socket

Registered agent ID

Enqueue or resume the agent in-process

"*"

Broadcast to all teammates via file mailbox

Teammate name

Write to teammate's file mailbox

结构化消息类型

Type	Purpose
shutdown_request	Request teammate to stop gracefully
shutdown_response	Acknowledge shutdown
plan_approval_response	Respond to plan mode approval request

邮箱系统

File-based messaging using JSON files with proper-lockfile to prevent race conditions when multiple teammates write to the same inbox simultaneously. Polled every 1 second by the useInboxPoller React hook.

消息格式

{
  from: string,       // Sender name
  text: string,       // Message content
  timestamp: number,  // Unix timestamp
  read: boolean,      // Read status
  color?: string,     // Sender's color (for UI)
  summary?: string    // Brief summary
}

Messages are injected into the teammate's context as XML:

<teammate-message teammate_id="frontend-dev" color="blue" summary="Found the CSS bug">
The issue is in src/styles/main.css line 42. The flex-direction
property is set to "column" but should be "row" for the header layout.
</teammate-message>

The inbox poller also handles: permission requests/responses, sandbox permissions, shutdown requests, team permission updates, mode set requests, and plan approval requests.

协调器模式 vs Team/Swarm

Aspect	Coordinator Mode	Team/Swarm
Topology	Hub-and-spoke	Peer-to-peer
Communication	Coordinator ↔ Workers only	Any teammate ↔ Any teammate
Coordinator tools	Agent, SendMessage, TaskStop only	Full toolset
Worker tools	Full toolset (no Agent/SendMessage)	Full toolset + SendMessage
Messaging	task-notification XML	File-based mailboxes (JSON)
Terminal UI	No special UI	Tmux split panes
Activation	CLAUDE_CODE_COORDINATOR_MODE=1	Agent tool with team_name param
Best for	Complex tasks needing strict orchestration	Collaborative parallel work

→ 使协调器模式安全的关键约束

协调器对文件系统零访问。它无法读取、写入或运行命令。对代码库的每个操作都必须通过工作者。这意味着协调器纯粹是一个推理和委托层 — 它可以计划和编排而不会意外地进行更改。