Back to Details

agent-teams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Table of Contents

目录

Agent Teams Coordination

Agent团队协调

Overview

概述

Claude Code Agent Teams enables multiple Claude CLI processes to collaborate on shared work through a filesystem-based coordination protocol. Each teammate runs as an independent 
claude
process in a tmux pane, communicating via JSON files guarded by 
fcntl
locks. No database, no daemon, no network layer.
This skill provides the patterns for orchestrating agent teams effectively.
Claude Code Agent Teams 允许多个Claude CLI进程通过基于文件系统的协调协议协作完成共同任务。每个团队成员作为独立的
claude
进程运行在tmux窗格中，通过受
fcntl
锁保护的JSON文件进行通信。无需数据库、守护进程或网络层。
本技能提供了有效编排Agent团队的模式。

When To Use

适用场景

  • Parallel implementation across multiple files or modules
  • Multi-agent code review (one agent reviews, another implements fixes)
  • Large refactoring requiring coordinated changes across subsystems
  • Tasks with natural parallelism that benefit from concurrent agents
  • 跨多个文件或模块的并行实现
  • 多Agent代码评审（一个Agent评审，另一个实现修复）
  • 需要跨子系统协调变更的大规模重构
  • 具有天然并行性、可从并发Agent中获益的任务

When NOT To Use

不适用场景

  • Single-file changes or small tasks (overhead exceeds benefit)
  • Tasks requiring tight sequential reasoning (agents coordinate loosely)
  • When 
    claude
    CLI is not available or tmux is not installed
  • 单文件变更或小型任务（开销超过收益）
  • 需要严格顺序推理的任务（Agent之间是松散协调）
  • 无法使用
    claude
    CLI或未安装tmux的场景

Prerequisites

前置条件

bash
undefined
bash
undefined

Verify Claude Code CLI

Verify Claude Code CLI

claude --version
claude --version

Verify tmux (required for split-pane mode)

Verify tmux (required for split-pane mode)

tmux -V
tmux -V

Enable experimental feature (set by spawner automatically)

Enable experimental feature (set by spawner automatically)

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
undefined
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
undefined

Protocol Architecture

协议架构

~/.claude/
  teams/<team-name>/
    config.json            # Team metadata + member roster
    inboxes/
      <agent-name>.json    # Per-agent message queue
      .lock                # fcntl exclusive lock
  tasks/<team-name>/
    1.json ... N.json      # Auto-incrementing task files
    .lock                  # fcntl exclusive lock
Design principles:
  • Filesystem is the database: JSON files, atomic writes via 
    tempfile
    + 
    os.replace
  • fcntl locking: Prevents concurrent read/write corruption on inboxes and tasks
  • Numbered tasks: Auto-incrementing IDs with sequential file naming
  • Loose coupling: Agents poll their own inbox; no push notifications
~/.claude/
  teams/<team-name>/
    config.json            # Team metadata + member roster
    inboxes/
      <agent-name>.json    # Per-agent message queue
      .lock                # fcntl exclusive lock
  tasks/<team-name>/
    1.json ... N.json      # Auto-incrementing task files
    .lock                  # fcntl exclusive lock
设计原则：
  • 文件系统即数据库：JSON文件，通过
    tempfile
    + 
    os.replace
    实现原子写入
  • fcntl锁：防止收件箱和任务文件的并发读写损坏
  • 编号任务：采用顺序文件命名的自增ID
  • 松耦合：Agent轮询自己的收件箱，无需推送通知

Quick Start

快速入门

1. Create a Team

1. 创建团队

bash
undefined
bash
undefined

Programmatic team setup (via MCP or direct API)

Programmatic team setup (via MCP or direct API)

Team config written to ~/.claude/teams/<team-name>/config.json

Team config written to ~/.claude/teams/<team-name>/config.json


The team config contains:
- `name`, `description`, `created_at` (ms timestamp)
- `lead_agent_id`, `lead_session_id`
- `members[]` — array of LeadMember and TeammateMember objects

团队配置包含：
- `name`、`description`、`created_at`（毫秒时间戳）
- `lead_agent_id`、`lead_session_id`
- `members[]` — 主管成员和团队成员对象的数组

2. Spawn Teammates

2. 生成团队成员

Each teammate is a separate 
claude
CLI process launched with identity flags:
bash
claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet
See 
modules/spawning-patterns.md
for tmux pane management and color assignment.
每个团队成员都是独立的
claude
CLI进程，通过身份标识参数启动：
bash
claude --agent-id "backend@my-team" \
       --agent-name "backend" \
       --team-name "my-team" \
       --agent-color "#FF6B6B" \
       --parent-session-id "$SESSION_ID" \
       --agent-type "general-purpose" \
       --model sonnet
请参考
modules/spawning-patterns.md
了解tmux窗格管理和颜色分配规则。

3. Create Tasks with Dependencies

3. 创建带依赖的任务

json
{
  "id": "1",
  "subject": "Implement API endpoints",
  "description": "Create REST endpoints for user management",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}
See 
modules/task-coordination.md
for state machine and dependency management.
json
{
  "id": "1",
  "subject": "Implement API endpoints",
  "description": "Create REST endpoints for user management",
  "status": "pending",
  "owner": null,
  "blocks": ["3"],
  "blocked_by": [],
  "metadata": {}
}
请参考
modules/task-coordination.md
了解状态机和依赖管理规则。

4. Coordinate via Messages

4. 通过消息协调

json
{
  "from": "team-lead",
  "text": "API endpoints are ready for integration testing",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API ready"
}
See 
modules/messaging-protocol.md
for message types and inbox operations.
json
{
  "from": "team-lead",
  "text": "API endpoints are ready for integration testing",
  "timestamp": "2026-02-07T22:00:00Z",
  "read": false,
  "summary": "API ready"
}
请参考
modules/messaging-protocol.md
了解消息类型和收件箱操作规则。

Coordination Workflow

协调工作流

  1. agent-teams:team-created
     — Initialize team config and directories
  2. agent-teams:teammates-spawned
     — Launch agents in tmux panes
  3. agent-teams:tasks-assigned
     — Create tasks with dependencies, assign owners
  4. agent-teams:coordination-active
     — Agents claim tasks, exchange messages, mark completion
  5. agent-teams:team-shutdown
     — Graceful shutdown with approval protocol
  1. agent-teams:team-created
     — 初始化团队配置和目录
  2. agent-teams:teammates-spawned
     — 在tmux窗格中启动Agent
  3. agent-teams:tasks-assigned
     — 创建带依赖的任务，分配负责人
  4. agent-teams:coordination-active
     — Agent认领任务、交换消息、标记完成状态
  5. agent-teams:team-shutdown
     — 遵循审批协议优雅关闭

Crew Roles

团队角色

Each team member has a 
role
that determines their capabilities and task compatibility. Five roles are defined: 
implementer
(default), 
researcher
, 
tester
, 
reviewer
, and 
architect
. Roles constrain which risk tiers an agent can handle — see 
modules/crew-roles.md
for the full capability matrix and role-risk compatibility table.
每个团队成员都有一个
role
属性，决定其能力和任务适配性。共定义了5种角色：
implementer
（默认）、
researcher
、
tester
、
reviewer
和
architect
。角色会限制Agent可处理的风险等级 — 完整的能力矩阵和角色-风险适配表请参考
modules/crew-roles.md
。

Health Monitoring

健康监控

Team members can be monitored for health via heartbeat messages and claim expiry. The lead polls team health every 60s with a 2-stage stall detection protocol (health_check probe + 30s wait). Stalled agents have their tasks released and are restarted or replaced following the "replace don't wait" doctrine. See 
modules/health-monitoring.md
for the full protocol and state machine.
可通过心跳消息和认领过期机制监控团队成员的健康状态。主管每60秒轮询一次团队健康状态，采用两阶段停滞检测协议（health_check探测 + 30秒等待）。停滞的Agent的任务会被释放，系统会遵循「替换而非等待」的原则重启或替换该Agent。完整协议和状态机请参考
modules/health-monitoring.md
。

Module Reference

模块参考

  • team-management.md: Team lifecycle, config format, member management
  • messaging-protocol.md: Message types, inbox operations, locking patterns
  • task-coordination.md: Task CRUD, state machine, dependency cycle detection
  • spawning-patterns.md: tmux spawning, CLI flags, pane management
  • crew-roles.md: Role taxonomy, capability matrix, role-risk compatibility
  • health-monitoring.md: Heartbeat protocol, stall detection, automated recovery
  • team-management.md：团队生命周期、配置格式、成员管理
  • messaging-protocol.md：消息类型、收件箱操作、锁模式
  • task-coordination.md：任务CRUD、状态机、依赖循环检测
  • spawning-patterns.md：tmux生成、CLI参数、窗格管理
  • crew-roles.md：角色分类、能力矩阵、角色-风险适配
  • health-monitoring.md：心跳协议、停滞检测、自动恢复

Integration with Conjure

与Conjure集成

Agent Teams extends the conjure delegation model:
Conjure PatternAgent Teams Equivalent
delegation-core:task-assessed
agent-teams:team-created
delegation-core:handoff-planned
agent-teams:tasks-assigned
delegation-core:results-integrated
agent-teams:team-shutdown
External LLM executionTeammate agent execution
Use 
Skill(conjure:delegation-core)
first to determine if the task benefits from multi-agent coordination vs. single-service delegation.
Agent Teams扩展了conjure委托模型：
Conjure模式Agent Teams对应项
delegation-core:task-assessed
agent-teams:team-created
delegation-core:handoff-planned
agent-teams:tasks-assigned
delegation-core:results-integrated
agent-teams:team-shutdown
外部LLM执行团队成员Agent执行
请先使用
Skill(conjure:delegation-core)
判断任务是否适合多Agent协调，还是单服务委托即可。

Worktree Isolation Alternative (Claude Code 2.1.49+)

工作树隔离替代方案（Claude Code 2.1.49+）

For parallel agents that modify files, 
isolation: worktree
provides a lightweight alternative to filesystem-based coordination. Each agent runs in its own temporary git worktree, eliminating the need for 
fcntl
locking or inbox-based conflict avoidance on shared files.
  • When to prefer worktrees over agent teams messaging: Agents work on overlapping files but don't need mid-execution communication
  • When to prefer agent teams messaging: Agents need to coordinate discoveries or adjust plans based on each other's progress
  • Combine both: Use agent teams for coordination with 
    isolation: worktree
    per teammate for filesystem safety
对于需要修改文件的并行Agent，
isolation: worktree
提供了基于文件系统协调的轻量替代方案。每个Agent运行在自己的临时git工作树中，无需
fcntl
锁或基于收件箱的共享文件冲突规避机制。
  • 何时优先选择工作树而非Agent团队消息机制：Agent处理重叠文件，但不需要执行中通信
  • 何时优先选择Agent团队消息机制：Agent需要协调发现内容或根据彼此的进度调整计划
  • 两者结合：使用Agent团队进行协调，同时为每个团队成员配置
    isolation: worktree
    保证文件系统安全

Troubleshooting

故障排查

Common Issues

常见问题

tmux not found Install via package manager: 
brew install tmux
/ 
apt install tmux
Stale lock files If an agent crashes mid-operation, lock files may persist. Remove 
.lock
files manually from 
~/.claude/teams/<team>/inboxes/
or 
~/.claude/tasks/<team>/
Orphaned tasks Tasks claimed by a crashed agent stay 
in_progress
indefinitely. Use 
modules/health-monitoring.md
for heartbeat-based stall detection and automatic task release. The health monitoring protocol detects unresponsive agents within 60s + 30s probe window and releases their tasks for reassignment.
Message ordering Filesystem timestamp resolution varies (HFS+ = 1s granularity). Use numbered filenames or UUID-sorted names to avoid collision on rapid message bursts.
Model errors on Bedrock/Vertex/Foundry (pre-2.1.39) Teammate agents could use incorrect model identifiers on enterprise providers, causing 400 errors. Upgrade to Claude Code 2.1.39+ for correct model ID qualification across all providers.
Nested session guard (2.1.39+) If 
claude
refuses to launch within an existing session, ensure you're using tmux pane splitting (not subshell invocation). The guard is intentional — see 
modules/spawning-patterns.md
for details.
tmux not found 通过包管理器安装：
brew install tmux
/ 
apt install tmux
锁文件残留 如果Agent运行中途崩溃，可能会残留锁文件。可手动删除
~/.claude/teams/<team>/inboxes/
或
~/.claude/tasks/<team>/
目录下的
.lock
文件
孤立任务 崩溃的Agent认领的任务会一直处于
in_progress
状态。可使用
modules/health-monitoring.md
中介绍的基于心跳的停滞检测机制自动释放任务。健康监控协议可在60秒 + 30秒探测窗口内检测到无响应的Agent，并释放其任务供重新分配。
消息排序问题 不同文件系统的时间戳精度不同（HFS+精度为1秒）。可使用编号文件名或UUID排序的文件名避免快速消息突发时的冲突。
Bedrock/Vertex/Foundry上的模型错误（2.1.39之前版本） 团队成员Agent可能在企业级提供商上使用错误的模型标识符，导致400错误。请升级到Claude Code 2.1.39+版本，以支持所有提供商的正确模型ID限定。
嵌套会话防护（2.1.39+） 如果
claude
拒绝在现有会话中启动，请确保你使用的是tmux窗格拆分（而非子shell调用）。该防护机制是有意设计的 — 详情请参考
modules/spawning-patterns.md
。

Exit Criteria

退出标准

  • Team created with config and directories
  • Teammates spawned and registered in config
  • Tasks created with dependency graph (no cycles)
  • Agents coordinating via inbox messages
  • Graceful shutdown completed
  • 已创建团队，包含配置和目录
  • 已生成团队成员并在配置中注册
  • 已创建任务，依赖图无循环
  • Agent通过收件箱消息正常协调
  • 优雅关闭完成