Claude Code 集群编排指南：掌握多智能体协同与任务管理系统

orchestrating-swarms by everyinc/compound-engineering-plugin

237 周安装量

10,900 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/everyinc/compound-engineering-plugin --skill orchestrating-swarms

AI/机器学习项目管理自动化

🇨🇳中文介绍

Claude Code 集群编排

使用 Claude Code 的 TeammateTool 和 Task 系统掌握多智能体编排。

基本概念

基本概念	定义	文件位置
智能体	可以使用工具的 Claude 实例。你就是一个智能体。子智能体是你创建的智能体。	N/A（进程）
团队	一起工作的命名智能体组。一个领导者，多个队友。	`~/.claude/teams/{name}/config.json`
队友	加入团队的智能体。拥有名称、颜色、收件箱。通过带有 `team_name` + `name` 的 Task 创建。	列在团队配置中
领导者	创建团队的智能体。接收队友消息，批准计划/关闭。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

776,000 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

104,600 周安装

flowchart TB
    subgraph TEAM[TEAM]
        Leader[Leader - you]
        T1[Teammate 1]
        T2[Teammate 2]

        Leader <-->|messages via inbox| T1
        Leader <-->|messages via inbox| T2
        T1 <-.->|can message| T2
    end

    subgraph TASKS[TASK LIST]
        Task1["#1 completed: Research<br/>owner: teammate1"]
        Task2["#2 in_progress: Implement<br/>owner: teammate2"]
        Task3["#3 pending: Test<br/>blocked by #2"]
    end

    T1 --> Task1
    T2 --> Task2
    Task2 -.->|unblocks| Task3

sequenceDiagram
    participant L as Leader
    participant T1 as Teammate 1
    participant T2 as Teammate 2
    participant Tasks as Task List

    L->>Tasks: TaskCreate (3 tasks)
    L->>T1: spawn with prompt
    L->>T2: spawn with prompt

    T1->>Tasks: claim task #1
    T2->>Tasks: claim task #2

    T1->>Tasks: complete #1
    T1->>L: send findings (inbox)

    Note over Tasks: #3 auto-unblocks

    T2->>Tasks: complete #2
    T2->>L: send findings (inbox)

    L->>T1: requestShutdown
    T1->>L: approveShutdown
    L->>T2: requestShutdown
    T2->>L: approveShutdown

    L->>L: cleanup

~/.claude/teams/{team-name}/
├── config.json              # 团队元数据和成员列表
└── inboxes/
    ├── team-lead.json       # 领导者的收件箱
    ├── worker-1.json        # 工作器 1 的收件箱
    └── worker-2.json        # 工作器 2 的收件箱

~/.claude/tasks/{team-name}/
├── 1.json                   # 任务 #1
├── 2.json                   # 任务 #2
└── 3.json                   # 任务 #3

{
  "name": "my-project",
  "description": "Working on feature X",
  "leadAgentId": "team-lead@my-project",
  "createdAt": 1706000000000,
  "members": [
    {
      "agentId": "team-lead@my-project",
      "name": "team-lead",
      "agentType": "team-lead",
      "color": "#4A90D9",
      "joinedAt": 1706000000000,
      "backendType": "in-process"
    },
    {
      "agentId": "worker-1@my-project",
      "name": "worker-1",
      "agentType": "Explore",
      "model": "haiku",
      "prompt": "Analyze the codebase structure...",
      "color": "#D94A4A",
      "planModeRequired": false,
      "joinedAt": 1706000001000,
      "tmuxPaneId": "in-process",
      "cwd": "/Users/me/project",
      "backendType": "in-process"
    }
  ]
}

// First create a team
Teammate({ operation: "spawnTeam", team_name: "my-project" })

// Then spawn a teammate into that team
Task({
  team_name: "my-project",        // Required: which team to join
  name: "security-reviewer",      // Required: teammate's name
  subagent_type: "security-sentinel",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
  run_in_background: true         // Teammates usually run in background
})

方面	Task（子智能体）	Task + team_name + name（队友）
生命周期	直到任务完成	直到请求关闭
通信	返回值	收件箱消息
任务访问	无	共享任务列表
团队成员身份	否	是
协调	一次性	持续进行

// Security review
Task({
  subagent_type: "compound-engineering:review:security-sentinel",
  description: "Security audit",
  prompt: "Audit this PR for security vulnerabilities"
})

// Performance review
Task({
  subagent_type: "compound-engineering:review:performance-oracle",
  description: "Performance check",
  prompt: "Analyze this code for performance bottlenecks"
})

// Rails code review
Task({
  subagent_type: "compound-engineering:review:kieran-rails-reviewer",
  description: "Rails review",
  prompt: "Review this Rails code for best practices"
})

// Architecture review
Task({
  subagent_type: "compound-engineering:review:architecture-strategist",
  description: "Architecture review",
  prompt: "Review the system architecture of the authentication module"
})

// Code simplicity
Task({
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  description: "Simplicity check",
  prompt: "Check if this implementation can be simplified"
})

agent-native-reviewer - 确保功能也适用于智能体
architecture-strategist - 架构合规性
code-simplicity-reviewer - YAGNI 和极简主义
data-integrity-guardian - 数据库和数据安全
data-migration-expert - 迁移验证
deployment-verification-agent - 部署前检查清单
dhh-rails-reviewer - DHH/37signals Rails 风格
julik-frontend-races-reviewer - JavaScript 竞态条件
kieran-python-reviewer - Python 最佳实践
kieran-rails-reviewer - Rails 最佳实践
kieran-typescript-reviewer - TypeScript 最佳实践
pattern-recognition-specialist - 设计模式和反模式
performance-oracle - 性能分析
security-sentinel - 安全漏洞

// Best practices research
Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research auth best practices",
  prompt: "Research current best practices for JWT authentication in Rails 2024-2026"
})

// Framework documentation
Task({
  subagent_type: "compound-engineering:research:framework-docs-researcher",
  description: "Research Active Storage",
  prompt: "Gather comprehensive documentation about Active Storage file uploads"
})

// Git history analysis
Task({
  subagent_type: "compound-engineering:research:git-history-analyzer",
  description: "Analyze auth history",
  prompt: "Analyze the git history of the authentication module to understand its evolution"
})

best-practices-researcher - 外部最佳实践
framework-docs-researcher - 框架文档
git-history-analyzer - 代码考古学
learnings-researcher - 搜索 docs/solutions/
repo-research-analyst - 仓库模式

// Create pipeline
TaskCreate({ subject: "Step 1: Research" })        // #1
TaskCreate({ subject: "Step 2: Implement" })       // #2
TaskCreate({ subject: "Step 3: Test" })            // #3
TaskCreate({ subject: "Step 4: Deploy" })          // #4

// Set up dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })   // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })   // #4 waits for #3

// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// etc.

{
  "type": "permission_request",
  "requestId": "perm-123",
  "workerId": "worker-1@my-project",
  "workerName": "worker-1",
  "workerColor": "#4A90D9",
  "toolName": "Bash",
  "toolUseId": "toolu_abc123",
  "description": "Run npm install",
  "input": {"command": "npm install"},
  "permissionSuggestions": ["Bash(npm *)"],
  "createdAt": 1706000000000
}

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "code-review" })

// 2. Spawn specialists in parallel (single message, multiple Task calls)
Task({
  team_name: "code-review",
  name: "security",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: "Review the PR for security vulnerabilities. Focus on: SQL injection, XSS, auth bypass. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "performance",
  subagent_type: "compound-engineering:review:performance-oracle",
  prompt: "Review the PR for performance issues. Focus on: N+1 queries, memory leaks, slow algorithms. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "simplicity",
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  prompt: "Review the PR for unnecessary complexity. Focus on: over-engineering, premature abstraction, YAGNI violations. Send findings to team-lead.",
  run_in_background: true
})

// 3. Wait for results (check inbox)
// cat ~/.claude/teams/code-review/inboxes/team-lead.json

// 4. Synthesize findings and cleanup
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "performance" })
Teammate({ operation: "requestShutdown", target_agent_id: "simplicity" })
// Wait for approvals...
Teammate({ operation: "cleanup" })

// 1. Create team and task pipeline
Teammate({ operation: "spawnTeam", team_name: "feature-pipeline" })

TaskCreate({ subject: "Research", description: "Research best practices for the feature", activeForm: "Researching..." })
TaskCreate({ subject: "Plan", description: "Create implementation plan based on research", activeForm: "Planning..." })
TaskCreate({ subject: "Implement", description: "Implement the feature according to plan", activeForm: "Implementing..." })
TaskCreate({ subject: "Test", description: "Write and run tests for the implementation", activeForm: "Testing..." })
TaskCreate({ subject: "Review", description: "Final code review before merge", activeForm: "Reviewing..." })

// Set up sequential dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })

// 2. Spawn workers that claim and complete tasks
Task({
  team_name: "feature-pipeline",
  name: "researcher",
  subagent_type: "compound-engineering:research:best-practices-researcher",
  prompt: "Claim task #1, research best practices, complete it, send findings to team-lead. Then check for more work.",
  run_in_background: true
})

Task({
  team_name: "feature-pipeline",
  name: "implementer",
  subagent_type: "general-purpose",
  prompt: "Poll TaskList every 30 seconds. When task #3 unblocks, claim it and implement. Then complete and notify team-lead.",
  run_in_background: true
})

// Tasks auto-unblock as dependencies complete

// 1. Create team and task pool
Teammate({ operation: "spawnTeam", team_name: "file-review-swarm" })

// Create many independent tasks (no dependencies)
for (const file of ["auth.rb", "user.rb", "api_controller.rb", "payment.rb"]) {
  TaskCreate({
    subject: `Review ${file}`,
    description: `Review ${file} for security and code quality issues`,
    activeForm: `Reviewing ${file}...`
  })
}

// 2. Spawn worker swarm
Task({
  team_name: "file-review-swarm",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: `
    You are a swarm worker. Your job:
    1. Call TaskList to see available tasks
    2. Find a task with status 'pending' and no owner
    3. Claim it with TaskUpdate (set owner to your name)
    4. Do the work
    5. Mark it completed with TaskUpdate
    6. Send findings to team-lead via Teammate write
    7. Repeat until no tasks remain
  `,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-2",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-3",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

// Workers race to claim tasks, naturally load-balance

// 1. Research phase (synchronous, returns results)
const research = await Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research caching patterns",
  prompt: "Research best practices for implementing caching in Rails APIs. Include: cache invalidation strategies, Redis vs Memcached, cache key design."
})

// 2. Use research to guide implementation
Task({
  subagent_type: "general-purpose",
  description: "Implement caching",
  prompt: `
    Implement API caching based on this research:

    ${research.content}

    Focus on the user_controller.rb endpoints.
  `
})

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "careful-work" })

// 2. Spawn architect with plan_mode_required
Task({
  team_name: "careful-work",
  name: "architect",
  subagent_type: "Plan",
  prompt: "Design an implementation plan for adding OAuth2 authentication",
  mode: "plan",  // Requires plan approval
  run_in_background: true
})

// 3. Wait for plan approval request
// You'll receive: {"type": "plan_approval_request", "from": "architect", "requestId": "plan-xxx", ...}

// 4. Review and approve/reject
Teammate({
  operation: "approvePlan",
  target_agent_id: "architect",
  request_id: "plan-xxx"
})
// OR
Teammate({
  operation: "rejectPlan",
  target_agent_id: "architect",
  request_id: "plan-xxx",
  feedback: "Please add rate limiting considerations"
})

// 1. Create team for coordinated refactoring
Teammate({ operation: "spawnTeam", team_name: "refactor-auth" })

// 2. Create tasks with clear file boundaries
TaskCreate({
  subject: "Refactor User model",
  description: "Extract authentication methods to AuthenticatableUser concern",
  activeForm: "Refactoring User model..."
})

TaskCreate({
  subject: "Refactor Session controller",
  description: "Update to use new AuthenticatableUser concern",
  activeForm: "Refactoring Sessions..."
})

TaskCreate({
  subject: "Update specs",
  description: "Update all authentication specs for new structure",
  activeForm: "Updating specs..."
})

// Dependencies: specs depend on both refactors completing
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

// 3. Spawn workers for each task
Task({
  team_name: "refactor-auth",
  name: "model-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #1, refactor the User model, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "controller-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #2, refactor the Session controller, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "spec-worker",
  subagent_type: "general-purpose",
  prompt: "Wait for task #3 to unblock (when #1 and #2 complete), then update specs",
  run_in_background: true
})

后端	工作原理	可见性	持久性	速度
in-process	与领导者相同的 Node.js 进程	隐藏（后台）	随领导者终止而终止	最快
tmux	tmux 会话中的独立终端	在 tmux 中可见	领导者退出后仍存在	中等
iterm2	iTerm2 窗口中的分割面板	并排可见	随窗口关闭而终止	中等

🇺🇸English

Claude Code Swarm Orchestration

Master multi-agent orchestration using Claude Code's TeammateTool and Task system.

Primitives

Primitive	What It Is	File Location
Agent	A Claude instance that can use tools. You are an agent. Subagents are agents you spawn.	N/A (process)
Team	A named group of agents working together. One leader, multiple teammates.	`~/.claude/teams/{name}/config.json`
Teammate	An agent that joined a team. Has a name, color, inbox. Spawned via Task with `team_name` + `name`.	Listed in team config
Leader	The agent that created the team. Receives teammate messages, approves plans/shutdowns.	First member in config
Task	A work item with subject, description, status, owner, and dependencies.	`~/.claude/tasks/{team}/N.json`
Inbox	JSON file where an agent receives messages from teammates.	`~/.claude/teams/{name}/inboxes/{agent}.json`
Message	A JSON object sent between agents. Can be text or structured (shutdown_request, idle_notification, etc).	Stored in inbox files
Backend	How teammates run. Auto-detected: `in-process` (same Node.js, invisible), `tmux` (separate panes, visible), `iterm2` (split panes in iTerm2). See Spawn Backends.	Auto-detected based on environment

How They Connect

flowchart TB
    subgraph TEAM[TEAM]
        Leader[Leader - you]
        T1[Teammate 1]
        T2[Teammate 2]

        Leader <-->|messages via inbox| T1
        Leader <-->|messages via inbox| T2
        T1 <-.->|can message| T2
    end

    subgraph TASKS[TASK LIST]
        Task1["#1 completed: Research<br/>owner: teammate1"]
        Task2["#2 in_progress: Implement<br/>owner: teammate2"]
        Task3["#3 pending: Test<br/>blocked by #2"]
    end

    T1 --> Task1
    T2 --> Task2
    Task2 -.->|unblocks| Task3

Lifecycle

flowchart LR
    A[1. Create Team] --> B[2. Create Tasks]
    B --> C[3. Spawn Teammates]
    C --> D[4. Work]
    D --> E[5. Coordinate]
    E --> F[6. Shutdown]
    F --> G[7. Cleanup]

Message Flow

sequenceDiagram
    participant L as Leader
    participant T1 as Teammate 1
    participant T2 as Teammate 2
    participant Tasks as Task List

    L->>Tasks: TaskCreate (3 tasks)
    L->>T1: spawn with prompt
    L->>T2: spawn with prompt

    T1->>Tasks: claim task #1
    T2->>Tasks: claim task #2

    T1->>Tasks: complete #1
    T1->>L: send findings (inbox)

    Note over Tasks: #3 auto-unblocks

    T2->>Tasks: complete #2
    T2->>L: send findings (inbox)

    L->>T1: requestShutdown
    T1->>L: approveShutdown
    L->>T2: requestShutdown
    T2->>L: approveShutdown

    L->>L: cleanup

Core Architecture
Two Ways to Spawn Agents
Built-in Agent Types
Plugin Agent Types
TeammateTool Operations
Task System Integration
Message Formats
Orchestration Patterns
Environment Variables
Spawn Backends
Error Handling
Complete Workflows

Core Architecture

How Swarms Work

A swarm consists of:

Leader (you) - Creates team, spawns workers, coordinates work
Teammates (spawned agents) - Execute tasks, report back
Task List - Shared work queue with dependencies
Inboxes - JSON files for inter-agent messaging

File Structure

~/.claude/teams/{team-name}/
├── config.json              # Team metadata and member list
└── inboxes/
    ├── team-lead.json       # Leader's inbox
    ├── worker-1.json        # Worker 1's inbox
    └── worker-2.json        # Worker 2's inbox

~/.claude/tasks/{team-name}/
├── 1.json                   # Task #1
├── 2.json                   # Task #2
└── 3.json                   # Task #3

Team Config Structure

{
  "name": "my-project",
  "description": "Working on feature X",
  "leadAgentId": "team-lead@my-project",
  "createdAt": 1706000000000,
  "members": [
    {
      "agentId": "team-lead@my-project",
      "name": "team-lead",
      "agentType": "team-lead",
      "color": "#4A90D9",
      "joinedAt": 1706000000000,
      "backendType": "in-process"
    },
    {
      "agentId": "worker-1@my-project",
      "name": "worker-1",
      "agentType": "Explore",
      "model": "haiku",
      "prompt": "Analyze the codebase structure...",
      "color": "#D94A4A",
      "planModeRequired": false,
      "joinedAt": 1706000001000,
      "tmuxPaneId": "in-process",
      "cwd": "/Users/me/project",
      "backendType": "in-process"
    }
  ]
}

Two Ways to Spawn Agents

Method 1: Task Tool (Subagents)

Use Task for short-lived, focused work that returns a result:

Task({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

Characteristics:

Runs synchronously (blocks until complete) or async with run_in_background: true
Returns result directly to you
No team membership required
Best for: searches, analysis, focused research

Method 2: Task Tool + team_name + name (Teammates)

Use Task with team_name and name to spawn persistent teammates :

// First create a team
Teammate({ operation: "spawnTeam", team_name: "my-project" })

// Then spawn a teammate into that team
Task({
  team_name: "my-project",        // Required: which team to join
  name: "security-reviewer",      // Required: teammate's name
  subagent_type: "security-sentinel",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead via Teammate write.",
  run_in_background: true         // Teammates usually run in background
})

Characteristics:

Joins team, appears in config.json
Communicates via inbox messages
Can claim tasks from shared task list
Persists until shutdown
Best for: parallel work, ongoing collaboration, pipeline stages

Key Difference

Aspect	Task (subagent)	Task + team_name + name (teammate)
Lifespan	Until task complete	Until shutdown requested
Communication	Return value	Inbox messages
Task access	None	Shared task list
Team membership	No	Yes
Coordination	One-off	Ongoing

Built-in Agent Types

These are always available without plugins:

Bash

Task({
  subagent_type: "Bash",
  description: "Run git commands",
  prompt: "Check git status and show recent commits"
})

Tools: Bash only
Model: Inherits from parent
Best for: Git operations, command execution, system tasks

Explore

Task({
  subagent_type: "Explore",
  description: "Find API endpoints",
  prompt: "Find all API endpoints in this codebase. Be very thorough.",
  model: "haiku"  // Fast and cheap
})

Tools: All read-only tools (no Edit, Write, NotebookEdit, Task)
Model: Haiku (optimized for speed)
Best for: Codebase exploration, file searches, code understanding
Thoroughness levels: "quick", "medium", "very thorough"

Plan

Task({
  subagent_type: "Plan",
  description: "Design auth system",
  prompt: "Create an implementation plan for adding OAuth2 authentication"
})

Tools: All read-only tools
Model: Inherits from parent
Best for: Architecture planning, implementation strategies

general-purpose

Task({
  subagent_type: "general-purpose",
  description: "Research and implement",
  prompt: "Research React Query best practices and implement caching for the user API"
})

Tools: All tools (*)
Model: Inherits from parent
Best for: Multi-step tasks, research + action combinations

claude-code-guide

Task({
  subagent_type: "claude-code-guide",
  description: "Help with Claude Code",
  prompt: "How do I configure MCP servers?"
})

Tools: Read-only + WebFetch + WebSearch
Best for: Questions about Claude Code, Agent SDK, Anthropic API

statusline-setup

Task({
  subagent_type: "statusline-setup",
  description: "Configure status line",
  prompt: "Set up a status line showing git branch and node version"
})

Tools: Read, Edit only
Model: Sonnet
Best for: Configuring Claude Code status line

Plugin Agent Types

From the compound-engineering plugin (examples):

Review Agents

// Security review
Task({
  subagent_type: "compound-engineering:review:security-sentinel",
  description: "Security audit",
  prompt: "Audit this PR for security vulnerabilities"
})

// Performance review
Task({
  subagent_type: "compound-engineering:review:performance-oracle",
  description: "Performance check",
  prompt: "Analyze this code for performance bottlenecks"
})

// Rails code review
Task({
  subagent_type: "compound-engineering:review:kieran-rails-reviewer",
  description: "Rails review",
  prompt: "Review this Rails code for best practices"
})

// Architecture review
Task({
  subagent_type: "compound-engineering:review:architecture-strategist",
  description: "Architecture review",
  prompt: "Review the system architecture of the authentication module"
})

// Code simplicity
Task({
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  description: "Simplicity check",
  prompt: "Check if this implementation can be simplified"
})

All review agents from compound-engineering:

agent-native-reviewer - Ensures features work for agents too
architecture-strategist - Architectural compliance
code-simplicity-reviewer - YAGNI and minimalism
data-integrity-guardian - Database and data safety
data-migration-expert - Migration validation
deployment-verification-agent - Pre-deploy checklists
dhh-rails-reviewer - DHH/37signals Rails style
julik-frontend-races-reviewer - JavaScript race conditions
kieran-python-reviewer - Python best practices

Research Agents

// Best practices research
Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research auth best practices",
  prompt: "Research current best practices for JWT authentication in Rails 2024-2026"
})

// Framework documentation
Task({
  subagent_type: "compound-engineering:research:framework-docs-researcher",
  description: "Research Active Storage",
  prompt: "Gather comprehensive documentation about Active Storage file uploads"
})

// Git history analysis
Task({
  subagent_type: "compound-engineering:research:git-history-analyzer",
  description: "Analyze auth history",
  prompt: "Analyze the git history of the authentication module to understand its evolution"
})

All research agents:

best-practices-researcher - External best practices
framework-docs-researcher - Framework documentation
git-history-analyzer - Code archaeology
learnings-researcher - Search docs/solutions/
repo-research-analyst - Repository patterns

Design Agents

Task({
  subagent_type: "compound-engineering:design:figma-design-sync",
  description: "Sync with Figma",
  prompt: "Compare implementation with Figma design at [URL]"
})

Workflow Agents

Task({
  subagent_type: "compound-engineering:workflow:bug-reproduction-validator",
  description: "Validate bug",
  prompt: "Reproduce and validate this reported bug: [description]"
})

TeammateTool Operations

1. spawnTeam - Create a Team

Teammate({
  operation: "spawnTeam",
  team_name: "feature-auth",
  description: "Implementing OAuth2 authentication"
})

Creates:

~/.claude/teams/feature-auth/config.json
~/.claude/tasks/feature-auth/ directory
You become the team leader

2. discoverTeams - List Available Teams

Teammate({ operation: "discoverTeams" })

Returns: List of teams you can join (not already a member of)

3. requestJoin - Request to Join Team

Teammate({
  operation: "requestJoin",
  team_name: "feature-auth",
  proposed_name: "helper",
  capabilities: "I can help with code review and testing"
})

4. approveJoin - Accept Join Request (Leader Only)

When you receive a join_request message:

{"type": "join_request", "proposedName": "helper", "requestId": "join-123", ...}

Approve it:

Teammate({
  operation: "approveJoin",
  target_agent_id: "helper",
  request_id: "join-123"
})

5. rejectJoin - Decline Join Request (Leader Only)

Teammate({
  operation: "rejectJoin",
  target_agent_id: "helper",
  request_id: "join-123",
  reason: "Team is at capacity"
})

6. write - Message One Teammate

Teammate({
  operation: "write",
  target_agent_id: "security-reviewer",
  value: "Please prioritize the authentication module. The deadline is tomorrow."
})

Important for teammates: Your text output is NOT visible to the team. You MUST use write to communicate.

7. broadcast - Message ALL Teammates

Teammate({
  operation: "broadcast",
  name: "team-lead",  // Your name
  value: "Status check: Please report your progress"
})

WARNING: Broadcasting is expensive - sends N separate messages for N teammates. Prefer write to specific teammates.

When to broadcast:

Critical issues requiring immediate attention
Major announcements affecting everyone

When NOT to broadcast:

Responding to one teammate
Normal back-and-forth
Information relevant to only some teammates

8. requestShutdown - Ask Teammate to Exit (Leader Only)

Teammate({
  operation: "requestShutdown",
  target_agent_id: "security-reviewer",
  reason: "All tasks complete, wrapping up"
})

9. approveShutdown - Accept Shutdown (Teammate Only)

When you receive a shutdown_request message:

{"type": "shutdown_request", "requestId": "shutdown-123", "from": "team-lead", "reason": "Done"}

MUST call:

Teammate({
  operation: "approveShutdown",
  request_id: "shutdown-123"
})

This sends confirmation and terminates your process.

10. rejectShutdown - Decline Shutdown (Teammate Only)

Teammate({
  operation: "rejectShutdown",
  request_id: "shutdown-123",
  reason: "Still working on task #3, need 5 more minutes"
})

11. approvePlan - Approve Teammate's Plan (Leader Only)

When teammate with plan_mode_required sends a plan:

{"type": "plan_approval_request", "from": "architect", "requestId": "plan-456", ...}

Approve:

Teammate({
  operation: "approvePlan",
  target_agent_id: "architect",
  request_id: "plan-456"
})

12. rejectPlan - Reject Plan with Feedback (Leader Only)

Teammate({
  operation: "rejectPlan",
  target_agent_id: "architect",
  request_id: "plan-456",
  feedback: "Please add error handling for the API calls and consider rate limiting"
})

13. cleanup - Remove Team Resources

Teammate({ operation: "cleanup" })

Removes:

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

IMPORTANT: Will fail if teammates are still active. Use requestShutdown first.

Task System Integration

TaskCreate - Create Work Items

TaskCreate({
  subject: "Review authentication module",
  description: "Review all files in app/services/auth/ for security vulnerabilities",
  activeForm: "Reviewing auth module..."  // Shown in spinner when in_progress
})

TaskList - See All Tasks

TaskList()

Returns:

#1 [completed] Analyze codebase structure
#2 [in_progress] Review authentication module (owner: security-reviewer)
#3 [pending] Generate summary report [blocked by #2]

TaskGet - Get Task Details

TaskGet({ taskId: "2" })

Returns full task with description, status, blockedBy, etc.

TaskUpdate - Update Task Status

// Claim a task
TaskUpdate({ taskId: "2", owner: "security-reviewer" })

// Start working
TaskUpdate({ taskId: "2", status: "in_progress" })

// Mark complete
TaskUpdate({ taskId: "2", status: "completed" })

// Set up dependencies
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

Task Dependencies

When a blocking task is completed, blocked tasks are automatically unblocked:

// Create pipeline
TaskCreate({ subject: "Step 1: Research" })        // #1
TaskCreate({ subject: "Step 2: Implement" })       // #2
TaskCreate({ subject: "Step 3: Test" })            // #3
TaskCreate({ subject: "Step 4: Deploy" })          // #4

// Set up dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })   // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })   // #4 waits for #3

// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// etc.

Task File Structure

~/.claude/tasks/{team-name}/1.json:

{
  "id": "1",
  "subject": "Review authentication module",
  "description": "Review all files in app/services/auth/...",
  "status": "in_progress",
  "owner": "security-reviewer",
  "activeForm": "Reviewing auth module...",
  "blockedBy": [],
  "blocks": ["3"],
  "createdAt": 1706000000000,
  "updatedAt": 1706000001000
}

Message Formats

Regular Message

{
  "from": "team-lead",
  "text": "Please prioritize the auth module",
  "timestamp": "2026-01-25T23:38:32.588Z",
  "read": false
}

Structured Messages (JSON in text field)

Shutdown Request

{
  "type": "shutdown_request",
  "requestId": "shutdown-abc123@worker-1",
  "from": "team-lead",
  "reason": "All tasks complete",
  "timestamp": "2026-01-25T23:38:32.588Z"
}

Shutdown Approved

{
  "type": "shutdown_approved",
  "requestId": "shutdown-abc123@worker-1",
  "from": "worker-1",
  "paneId": "%5",
  "backendType": "in-process",
  "timestamp": "2026-01-25T23:39:00.000Z"
}

Idle Notification (auto-sent when teammate stops)

{
  "type": "idle_notification",
  "from": "worker-1",
  "timestamp": "2026-01-25T23:40:00.000Z",
  "completedTaskId": "2",
  "completedStatus": "completed"
}

Task Completed

{
  "type": "task_completed",
  "from": "worker-1",
  "taskId": "2",
  "taskSubject": "Review authentication module",
  "timestamp": "2026-01-25T23:40:00.000Z"
}

Plan Approval Request

{
  "type": "plan_approval_request",
  "from": "architect",
  "requestId": "plan-xyz789",
  "planContent": "# Implementation Plan\n\n1. ...",
  "timestamp": "2026-01-25T23:41:00.000Z"
}

Join Request

{
  "type": "join_request",
  "proposedName": "helper",
  "requestId": "join-abc123",
  "capabilities": "Code review and testing",
  "timestamp": "2026-01-25T23:42:00.000Z"
}

Permission Request (for sandbox/tool permissions)

{
  "type": "permission_request",
  "requestId": "perm-123",
  "workerId": "worker-1@my-project",
  "workerName": "worker-1",
  "workerColor": "#4A90D9",
  "toolName": "Bash",
  "toolUseId": "toolu_abc123",
  "description": "Run npm install",
  "input": {"command": "npm install"},
  "permissionSuggestions": ["Bash(npm *)"],
  "createdAt": 1706000000000
}

Orchestration Patterns

Pattern 1: Parallel Specialists (Leader Pattern)

Multiple specialists review code simultaneously:

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "code-review" })

// 2. Spawn specialists in parallel (single message, multiple Task calls)
Task({
  team_name: "code-review",
  name: "security",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: "Review the PR for security vulnerabilities. Focus on: SQL injection, XSS, auth bypass. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "performance",
  subagent_type: "compound-engineering:review:performance-oracle",
  prompt: "Review the PR for performance issues. Focus on: N+1 queries, memory leaks, slow algorithms. Send findings to team-lead.",
  run_in_background: true
})

Task({
  team_name: "code-review",
  name: "simplicity",
  subagent_type: "compound-engineering:review:code-simplicity-reviewer",
  prompt: "Review the PR for unnecessary complexity. Focus on: over-engineering, premature abstraction, YAGNI violations. Send findings to team-lead.",
  run_in_background: true
})

// 3. Wait for results (check inbox)
// cat ~/.claude/teams/code-review/inboxes/team-lead.json

// 4. Synthesize findings and cleanup
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "performance" })
Teammate({ operation: "requestShutdown", target_agent_id: "simplicity" })
// Wait for approvals...
Teammate({ operation: "cleanup" })

Pattern 2: Pipeline (Sequential Dependencies)

Each stage depends on the previous:

// 1. Create team and task pipeline
Teammate({ operation: "spawnTeam", team_name: "feature-pipeline" })

TaskCreate({ subject: "Research", description: "Research best practices for the feature", activeForm: "Researching..." })
TaskCreate({ subject: "Plan", description: "Create implementation plan based on research", activeForm: "Planning..." })
TaskCreate({ subject: "Implement", description: "Implement the feature according to plan", activeForm: "Implementing..." })
TaskCreate({ subject: "Test", description: "Write and run tests for the implementation", activeForm: "Testing..." })
TaskCreate({ subject: "Review", description: "Final code review before merge", activeForm: "Reviewing..." })

// Set up sequential dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })

// 2. Spawn workers that claim and complete tasks
Task({
  team_name: "feature-pipeline",
  name: "researcher",
  subagent_type: "compound-engineering:research:best-practices-researcher",
  prompt: "Claim task #1, research best practices, complete it, send findings to team-lead. Then check for more work.",
  run_in_background: true
})

Task({
  team_name: "feature-pipeline",
  name: "implementer",
  subagent_type: "general-purpose",
  prompt: "Poll TaskList every 30 seconds. When task #3 unblocks, claim it and implement. Then complete and notify team-lead.",
  run_in_background: true
})

// Tasks auto-unblock as dependencies complete

Pattern 3: Swarm (Self-Organizing)

Workers grab available tasks from a pool:

// 1. Create team and task pool
Teammate({ operation: "spawnTeam", team_name: "file-review-swarm" })

// Create many independent tasks (no dependencies)
for (const file of ["auth.rb", "user.rb", "api_controller.rb", "payment.rb"]) {
  TaskCreate({
    subject: `Review ${file}`,
    description: `Review ${file} for security and code quality issues`,
    activeForm: `Reviewing ${file}...`
  })
}

// 2. Spawn worker swarm
Task({
  team_name: "file-review-swarm",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: `
    You are a swarm worker. Your job:
    1. Call TaskList to see available tasks
    2. Find a task with status 'pending' and no owner
    3. Claim it with TaskUpdate (set owner to your name)
    4. Do the work
    5. Mark it completed with TaskUpdate
    6. Send findings to team-lead via Teammate write
    7. Repeat until no tasks remain
  `,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-2",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

Task({
  team_name: "file-review-swarm",
  name: "worker-3",
  subagent_type: "general-purpose",
  prompt: `[Same prompt as worker-1]`,
  run_in_background: true
})

// Workers race to claim tasks, naturally load-balance

Pattern 4: Research + Implementation

Research first, then implement:

// 1. Research phase (synchronous, returns results)
const research = await Task({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research caching patterns",
  prompt: "Research best practices for implementing caching in Rails APIs. Include: cache invalidation strategies, Redis vs Memcached, cache key design."
})

// 2. Use research to guide implementation
Task({
  subagent_type: "general-purpose",
  description: "Implement caching",
  prompt: `
    Implement API caching based on this research:

    ${research.content}

    Focus on the user_controller.rb endpoints.
  `
})

Pattern 5: Plan Approval Workflow

Require plan approval before implementation:

// 1. Create team
Teammate({ operation: "spawnTeam", team_name: "careful-work" })

// 2. Spawn architect with plan_mode_required
Task({
  team_name: "careful-work",
  name: "architect",
  subagent_type: "Plan",
  prompt: "Design an implementation plan for adding OAuth2 authentication",
  mode: "plan",  // Requires plan approval
  run_in_background: true
})

// 3. Wait for plan approval request
// You'll receive: {"type": "plan_approval_request", "from": "architect", "requestId": "plan-xxx", ...}

// 4. Review and approve/reject
Teammate({
  operation: "approvePlan",
  target_agent_id: "architect",
  request_id: "plan-xxx"
})
// OR
Teammate({
  operation: "rejectPlan",
  target_agent_id: "architect",
  request_id: "plan-xxx",
  feedback: "Please add rate limiting considerations"
})

Pattern 6: Coordinated Multi-File Refactoring

// 1. Create team for coordinated refactoring
Teammate({ operation: "spawnTeam", team_name: "refactor-auth" })

// 2. Create tasks with clear file boundaries
TaskCreate({
  subject: "Refactor User model",
  description: "Extract authentication methods to AuthenticatableUser concern",
  activeForm: "Refactoring User model..."
})

TaskCreate({
  subject: "Refactor Session controller",
  description: "Update to use new AuthenticatableUser concern",
  activeForm: "Refactoring Sessions..."
})

TaskCreate({
  subject: "Update specs",
  description: "Update all authentication specs for new structure",
  activeForm: "Updating specs..."
})

// Dependencies: specs depend on both refactors completing
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

// 3. Spawn workers for each task
Task({
  team_name: "refactor-auth",
  name: "model-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #1, refactor the User model, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "controller-worker",
  subagent_type: "general-purpose",
  prompt: "Claim task #2, refactor the Session controller, complete when done",
  run_in_background: true
})

Task({
  team_name: "refactor-auth",
  name: "spec-worker",
  subagent_type: "general-purpose",
  prompt: "Wait for task #3 to unblock (when #1 and #2 complete), then update specs",
  run_in_background: true
})

Environment Variables

Spawned teammates automatically receive these:

CLAUDE_CODE_TEAM_NAME="my-project"
CLAUDE_CODE_AGENT_ID="worker-1@my-project"
CLAUDE_CODE_AGENT_NAME="worker-1"
CLAUDE_CODE_AGENT_TYPE="Explore"
CLAUDE_CODE_AGENT_COLOR="#4A90D9"
CLAUDE_CODE_PLAN_MODE_REQUIRED="false"
CLAUDE_CODE_PARENT_SESSION_ID="session-xyz"

Using in prompts:

Task({
  team_name: "my-project",
  name: "worker",
  subagent_type: "general-purpose",
  prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages to team-lead."
})

Spawn Backends

A backend determines how teammate Claude instances actually run. Claude Code supports three backends, and auto-detects the best one based on your environment.

Backend Comparison

Backend	How It Works	Visibility	Persistence	Speed
in-process	Same Node.js process as leader	Hidden (background)	Dies with leader	Fastest
tmux	Separate terminal in tmux session	Visible in tmux	Survives leader exit	Medium
iterm2	Split panes in iTerm2 window	Visible side-by-side	Dies with window	Medium

Auto-Detection Logic

Claude Code automatically selects a backend using this decision tree:

flowchart TD
    A[Start] --> B{Running inside tmux?}
    B -->|Yes| C[Use tmux backend]
    B -->|No| D{Running in iTerm2?}
    D -->|No| E{tmux available?}
    E -->|Yes| F[Use tmux - external session]
    E -->|No| G[Use in-process]
    D -->|Yes| H{it2 CLI installed?}
    H -->|Yes| I[Use iterm2 backend]
    H -->|No| J{tmux available?}
    J -->|Yes| K[Use tmux - prompt to install it2]
    J -->|No| L[Error: Install tmux or it2]

Detection checks:

$TMUX environment variable → inside tmux
$TERM_PROGRAM === "iTerm.app" or $ITERM_SESSION_ID → in iTerm2
which tmux → tmux available
which it2 → it2 CLI installed

in-process (Default for non-tmux)

Teammates run as async tasks within the same Node.js process.

How it works:

No new process spawned
Teammates share the same Node.js event loop
Communication via in-memory queues (fast)
You don't see teammate output directly

When it's used:

Not running inside tmux session
Non-interactive mode (CI, scripts)
Explicitly set via CLAUDE_CODE_SPAWN_BACKEND=in-process

Characteristics:

┌─────────────────────────────────────────┐
│           Node.js Process               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │ Leader  │  │Worker 1 │  │Worker 2 │ │
│  │ (main)  │  │ (async) │  │ (async) │ │
│  └─────────┘  └─────────┘  └─────────┘ │
└─────────────────────────────────────────┘

Pros:

Fastest startup (no process spawn)
Lowest overhead
Works everywhere

Cons:

Can't see teammate output in real-time
All die if leader dies
Harder to debug

// in-process is automatic when not in tmux Task({ team_name: "my-project", name: "worker", subagent_type: "general-purpose", prompt: "...", run_in_background: true })

// Force in-process explicitly // export CLAUDE_CODE_SPAWN_BACKEND=in-process

tmux

Teammates run as separate Claude instances in tmux panes/windows.

How it works:

Each teammate gets its own tmux pane
Separate process per teammate
You can switch panes to see teammate output
Communication via inbox files

When it's used:

Running inside a tmux session ($TMUX is set)
tmux available and not in iTerm2
Explicitly set via CLAUDE_CODE_SPAWN_BACKEND=tmux

Layout modes:

Inside tmux (native): Splits your current window

┌─────────────────┬─────────────────┐

│                 │    Worker 1     │
│     Leader      ├─────────────────┤
│   (your pane)   │    Worker 2     │
│                 ├─────────────────┤
│                 │    Worker 3     │
└─────────────────┴─────────────────┘

2. Outside tmux (external session): Creates a new tmux session called claude-swarm

# Your terminal stays as-is
# Workers run in separate tmux session

# View workers:
tmux attach -t claude-swarm

Pros:

See teammate output in real-time
Teammates survive leader exit
Can attach/detach sessions
Works in CI/headless environments

Cons:

Slower startup (process spawn)
Requires tmux installed
More resource usage

Start tmux session first

tmux new-session -s claude

Or force tmux backend

export CLAUDE_CODE_SPAWN_BACKEND=tmux

Useful tmux commands:

# List all panes in current window
tmux list-panes

# Switch to pane by number
tmux select-pane -t 1

# Kill a specific pane
tmux kill-pane -t %5

# View swarm session (if external)
tmux attach -t claude-swarm

# Rebalance pane layout
tmux select-layout tiled

iterm2 (macOS only)

Teammates run as split panes within your iTerm2 window.

How it works:

Uses iTerm2's Python API via it2 CLI
Splits your current window into panes
Each teammate visible side-by-side
Communication via inbox files

When it's used:

Running in iTerm2 ($TERM_PROGRAM === "iTerm.app")
it2 CLI is installed and working
Python API enabled in iTerm2 preferences

Layout:

┌─────────────────┬─────────────────┐
│                 │    Worker 1     │
│     Leader      ├─────────────────┤
│   (your pane)   │    Worker 2     │
│                 ├─────────────────┤
│                 │    Worker 3     │
└─────────────────┴─────────────────┘

Pros:

Visual debugging - see all teammates
Native macOS experience
No tmux needed
Automatic pane management

Cons:

macOS + iTerm2 only
Requires setup (it2 CLI + Python API)
Panes die with window

Setup:

# 1. Install it2 CLI
uv tool install it2
# OR
pipx install it2
# OR
pip install --user it2

# 2. Enable Python API in iTerm2
# iTerm2 → Settings → General → Magic → Enable Python API

# 3. Restart iTerm2

# 4. Verify
it2 --version
it2 session list

If setup fails: Claude Code will prompt you to set up it2 when you first spawn a teammate. You can choose to:

Install it2 now (guided setup)
Use tmux instead
Cancel

Forcing a Backend

# Force in-process (fastest, no visibility)
export CLAUDE_CODE_SPAWN_BACKEND=in-process

# Force tmux (visible panes, persistent)
export CLAUDE_CODE_SPAWN_BACKEND=tmux

# Auto-detect (default)
unset CLAUDE_CODE_SPAWN_BACKEND

Backend in Team Config

The backend type is recorded per-teammate in config.json:

{
  "members": [
    {
      "name": "worker-1",
      "backendType": "in-process",
      "tmuxPaneId": "in-process"
    },
    {
      "name": "worker-2",
      "backendType": "tmux",
      "tmuxPaneId": "%5"
    }
  ]
}

Troubleshooting Backends

Issue	Cause	Solution
"No pane backend available"	Neither tmux nor iTerm2 available	Install tmux: `brew install tmux`
"it2 CLI not installed"	In iTerm2 but missing it2	Run `uv tool install it2`
"Python API not enabled"	it2 can't communicate with iTerm2	Enable in iTerm2 Settings → General → Magic
Workers not visible	Using in-process backend	Start inside tmux or iTerm2
Workers dying unexpectedly	Outside tmux, leader exited	Use tmux for persistence

Checking Current Backend

# See what backend was detected
cat ~/.claude/teams/{team}/config.json | jq '.members[].backendType'

# Check if inside tmux
echo $TMUX

# Check if in iTerm2
echo $TERM_PROGRAM

# Check tmux availability
which tmux

# Check it2 availability
which it2

Error Handling

Common Errors

Error	Cause	Solution
"Cannot cleanup with active members"	Teammates still running	`requestShutdown` all teammates first, wait for approval
"Already leading a team"	Team already exists	`cleanup` first, or use different team name
"Agent not found"	Wrong teammate name	Check `config.json` for actual names
"Team does not exist"	No team created	Call `spawnTeam` first
"team_name is required"	Missing team context	Provide `team_name` parameter

Graceful Shutdown Sequence

Always follow this sequence:

// 1. Request shutdown for all teammates
Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
Teammate({ operation: "requestShutdown", target_agent_id: "worker-2" })

// 2. Wait for shutdown approvals
// Check for {"type": "shutdown_approved", ...} messages

// 3. Verify no active members
// Read ~/.claude/teams/{team}/config.json

// 4. Only then cleanup
Teammate({ operation: "cleanup" })

Handling Crashed Teammates

Teammates have a 5-minute heartbeat timeout. If a teammate crashes:

They'll be automatically marked as inactive after timeout
Their tasks remain in the task list
Another teammate can claim their tasks
Cleanup will work after timeout expires

Debugging

# Check team config
cat ~/.claude/teams/{team}/config.json | jq '.members[] | {name, agentType, backendType}'

# Check teammate inboxes
cat ~/.claude/teams/{team}/inboxes/{agent}.json | jq '.'

# List all teams
ls ~/.claude/teams/

# Check task states
cat ~/.claude/tasks/{team}/*.json | jq '{id, subject, status, owner, blockedBy}'

# Watch for new messages
tail -f ~/.claude/teams/{team}/inboxes/team-lead.json

Complete Workflows

Workflow 1: Full Code Review with Parallel Specialists

// === STEP 1: Setup ===
Teammate({ operation: "spawnTeam", team_name: "pr-review-123", description: "Reviewing PR #123" })

// === STEP 2: Spawn reviewers in parallel ===
// (Send all these in a single message for parallel execution)
Task({
  team_name: "pr-review-123",
  name: "security",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: `Review PR #123 for security vulnerabilities.

  Focus on:
  - SQL injection
  - XSS vulnerabilities
  - Authentication/authorization bypass
  - Sensitive data exposure

  When done, send your findings to team-lead using:
  Teammate({ operation: "write", target_agent_id: "team-lead", value: "Your findings here" })`,
  run_in_background: true
})

Task({
  team_name: "pr-review-123",
  name: "perf",
  subagent_type: "compound-engineering:review:performance-oracle",
  prompt: `Review PR #123 for performance issues.

  Focus on:
  - N+1 queries
  - Missing indexes
  - Memory leaks
  - Inefficient algorithms

  Send findings to team-lead when done.`,
  run_in_background: true
})

Task({
  team_name: "pr-review-123",
  name: "arch",
  subagent_type: "compound-engineering:review:architecture-strategist",
  prompt: `Review PR #123 for architectural concerns.

  Focus on:
  - Design pattern adherence
  - SOLID principles
  - Separation of concerns
  - Testability

  Send findings to team-lead when done.`,
  run_in_background: true
})

// === STEP 3: Monitor and collect results ===
// Poll inbox or wait for idle notifications
// cat ~/.claude/teams/pr-review-123/inboxes/team-lead.json

// === STEP 4: Synthesize findings ===
// Combine all reviewer findings into a cohesive report

// === STEP 5: Cleanup ===
Teammate({ operation: "requestShutdown", target_agent_id: "security" })
Teammate({ operation: "requestShutdown", target_agent_id: "perf" })
Teammate({ operation: "requestShutdown", target_agent_id: "arch" })
// Wait for approvals...
Teammate({ operation: "cleanup" })

Workflow 2: Research → Plan → Implement → Test Pipeline

// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "feature-oauth" })

// === CREATE PIPELINE ===
TaskCreate({ subject: "Research OAuth providers", description: "Research OAuth2 best practices and compare providers (Google, GitHub, Auth0)", activeForm: "Researching OAuth..." })
TaskCreate({ subject: "Create implementation plan", description: "Design OAuth implementation based on research findings", activeForm: "Planning..." })
TaskCreate({ subject: "Implement OAuth", description: "Implement OAuth2 authentication according to plan", activeForm: "Implementing OAuth..." })
TaskCreate({ subject: "Write tests", description: "Write comprehensive tests for OAuth implementation", activeForm: "Writing tests..." })
TaskCreate({ subject: "Final review", description: "Review complete implementation for security and quality", activeForm: "Final review..." })

// Set dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
TaskUpdate({ taskId: "5", addBlockedBy: ["4"] })

// === SPAWN SPECIALIZED WORKERS ===
Task({
  team_name: "feature-oauth",
  name: "researcher",
  subagent_type: "compound-engineering:research:best-practices-researcher",
  prompt: "Claim task #1. Research OAuth2 best practices, compare providers, document findings. Mark task complete and send summary to team-lead.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "planner",
  subagent_type: "Plan",
  prompt: "Wait for task #2 to unblock. Read research from task #1. Create detailed implementation plan. Mark complete and send plan to team-lead.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "implementer",
  subagent_type: "general-purpose",
  prompt: "Wait for task #3 to unblock. Read plan from task #2. Implement OAuth2 authentication. Mark complete when done.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "tester",
  subagent_type: "general-purpose",
  prompt: "Wait for task #4 to unblock. Write comprehensive tests for the OAuth implementation. Run tests. Mark complete with results.",
  run_in_background: true
})

Task({
  team_name: "feature-oauth",
  name: "reviewer",
  subagent_type: "compound-engineering:review:security-sentinel",
  prompt: "Wait for task #5 to unblock. Review the complete OAuth implementation for security. Send final assessment to team-lead.",
  run_in_background: true
})

// Pipeline auto-progresses as each stage completes

Workflow 3: Self-Organizing Code Review Swarm

// === SETUP ===
Teammate({ operation: "spawnTeam", team_name: "codebase-review" })

// === CREATE TASK POOL (all independent, no dependencies) ===
const filesToReview = [
  "app/models/user.rb",
  "app/models/payment.rb",
  "app/controllers/api/v1/users_controller.rb",
  "app/controllers/api/v1/payments_controller.rb",
  "app/services/payment_processor.rb",
  "app/services/notification_service.rb",
  "lib/encryption_helper.rb"
]

for (const file of filesToReview) {
  TaskCreate({
    subject: `Review ${file}`,
    description: `Review ${file} for security vulnerabilities, code quality, and performance issues`,
    activeForm: `Reviewing ${file}...`
  })
}

// === SPAWN WORKER SWARM ===
const swarmPrompt = `
You are a swarm worker. Your job is to continuously process available tasks.

LOOP:
1. Call TaskList() to see available tasks
2. Find a task that is:
   - status: 'pending'
   - no owner
   - not blocked
3. If found:
   - Claim it: TaskUpdate({ taskId: "X", owner: "YOUR_NAME" })
   - Start it: TaskUpdate({ taskId: "X", status: "in_progress" })
   - Do the review work
   - Complete it: TaskUpdate({ taskId: "X", status: "completed" })
   - Send findings to team-lead via Teammate write
   - Go back to step 1
4. If no tasks available:
   - Send idle notification to team-lead
   - Wait 30 seconds
   - Try again (up to 3 times)
   - If still no tasks, exit

Replace YOUR_NAME with your actual agent name from $CLAUDE_CODE_AGENT_NAME.
`

// Spawn 3 workers
Task({ team_name: "codebase-review", name: "worker-1", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-2", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })
Task({ team_name: "codebase-review", name: "worker-3", subagent_type: "general-purpose", prompt: swarmPrompt, run_in_background: true })

// Workers self-organize: race to claim tasks, naturally load-balance
// Monitor progress with TaskList() or by reading inbox

Best Practices

1. Always Cleanup

Don't leave orphaned teams. Always call cleanup when done.

2. Use Meaningful Names

// Good
name: "security-reviewer"
name: "oauth-implementer"
name: "test-writer"

// Bad
name: "worker-1"
name: "agent-2"

3. Write Clear Prompts

Tell workers exactly what to do:

// Good
prompt: `
  1. Review app/models/user.rb for N+1 queries
  2. Check all ActiveRecord associations have proper includes
  3. Document any issues found
  4. Send findings to team-lead via Teammate write
`

// Bad
prompt: "Review the code"

4. Use Task Dependencies

Let the system manage unblocking:

// Good: Auto-unblocking
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })

// Bad: Manual polling
"Wait until task #1 is done, check every 30 seconds..."

5. Check Inboxes for Results

Workers send results to your inbox. Check it:

cat ~/.claude/teams/{team}/inboxes/team-lead.json | jq '.'

6. Handle Worker Failures

Workers have 5-minute heartbeat timeout
Tasks of crashed workers can be reclaimed
Build retry logic into worker prompts

7. Prefer write Over broadcast

broadcast sends N messages for N teammates. Use write for targeted communication.

8. Match Agent Type to Task

Explore for searching/reading
Plan for architecture design
general-purpose for implementation
Specialized reviewers for specific review types

Quick Reference

Spawn Subagent (No Team)

Task({ subagent_type: "Explore", description: "Find files", prompt: "..." })

Spawn Teammate (With Team)

Teammate({ operation: "spawnTeam", team_name: "my-team" })
Task({ team_name: "my-team", name: "worker", subagent_type: "general-purpose", prompt: "...", run_in_background: true })

Message Teammate

Teammate({ operation: "write", target_agent_id: "worker-1", value: "..." })

Create Task Pipeline

TaskCreate({ subject: "Step 1", description: "..." })
TaskCreate({ subject: "Step 2", description: "..." })
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })

Shutdown Team

Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
// Wait for approval...
Teammate({ operation: "cleanup" })

Based on Claude Code v2.1.19 - Tested and verified 2026-01-25

Weekly Installs

237

Repository

everyinc/compou…g-plugin

GitHub Stars

10.9K

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex223

opencode223

gemini-cli219

github-copilot215

cursor201

kimi-cli196

Claude Code 集群编排指南：掌握多智能体协同与任务管理系统

🇨🇳中文介绍

Claude Code 集群编排

基本概念

相关 Skills

它们如何连接

生命周期

消息流

目录

核心架构

集群如何工作

文件结构

团队配置结构

两种生成智能体的方式

方法 1：Task 工具（子智能体）

方法 2：Task 工具 + team_name + name（队友）

关键区别

内置智能体类型

Bash

Explore

Plan

general-purpose

claude-code-guide

statusline-setup

插件智能体类型

审查智能体

研究智能体

设计智能体

工作流智能体

TeammateTool 操作

1. spawnTeam - 创建团队

2. discoverTeams - 列出可用团队

3. requestJoin - 请求加入团队

4. approveJoin - 接受加入请求（仅限领导者）

5. rejectJoin - 拒绝加入请求（仅限领导者）

6. write - 向一个队友发送消息

7. broadcast - 向所有队友发送消息

8. requestShutdown - 请求队友退出（仅限领导者）

9. approveShutdown - 接受关闭（仅限队友）

10. rejectShutdown - 拒绝关闭（仅限队友）

11. approvePlan - 批准队友的计划（仅限领导者）

12. rejectPlan - 拒绝计划并提供反馈（仅限领导者）

13. cleanup - 移除团队资源

任务系统集成

TaskCreate - 创建工作项

TaskList - 查看所有任务

TaskGet - 获取任务详情

TaskUpdate - 更新任务状态

任务依赖关系

任务文件结构

消息格式

常规消息

结构化消息（文本字段中的 JSON）

关闭请求

关闭已批准

空闲通知（当队友停止时自动发送）

任务已完成

计划批准请求

加入请求

权限请求（用于沙盒/工具权限）

编排模式

模式 1：并行专家（领导者模式）

模式 2：流水线（顺序依赖）

模式 3：集群（自组织）

模式 4：研究 + 实施

模式 5：计划批准工作流

模式 6：协调的多文件重构

环境变量

生成后端

后端比较

自动检测逻辑

🇺🇸English

Claude Code Swarm Orchestration

Primitives

How They Connect

Lifecycle

Message Flow

Table of Contents

Core Architecture

How Swarms Work