tools-only Swarm Operations
API reference for multi-agent orchestration tools in Claude Code v2.1.45.
Tools Overview
flowchart TD
Start([What do you need to do?]) --> Q1{Operation type?}
Q1 -->|Create a team| TC[TeamCreate]
Q1 -->|Send a message| SM[SendMessage]
Q1 -->|Clean up team| TD[TeamDelete]
Q1 -->|Spawn an agent| Task[Task tool]
Q1 -->|Manage work items| TT[TaskCreate / TaskUpdate / TaskList / TaskGet]
TeamCreate -- Create a Team
TeamCreate({
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
SendMessage -- All Inter-Agent Communication
SendMessage handles direct messages, broadcasts, shutdown, and plan approval.
Direct Message (type "message")
SendMessage({
type: "message",
recipient: "security-reviewer",
content: "Please prioritize the authentication module. The deadline is tomorrow.",
summary: "Prioritize auth module"
})
Required fields: type, recipient, content, summary
IMPORTANT: Your text output is NOT visible to teammates. You MUST use SendMessage to communicate.
Broadcast (type "broadcast")
SendMessage({
type: "broadcast",
content: "Status check: Please report your progress",
summary: "Requesting status from all"
})
Required fields: type, content, summary
WARNING: Broadcasting is expensive -- sends N separate messages for N teammates. Prefer direct message to specific teammates.
When to broadcast:
- Critical issues requiring immediate team-wide attention
- Major announcements affecting everyone
When NOT to broadcast:
- Responding to one teammate
- Normal back-and-forth
- Information relevant to only some teammates
Shutdown Request (type "shutdown_request")
Leader requests teammate to exit:
SendMessage({
type: "shutdown_request",
recipient: "security-reviewer",
content: "All tasks complete, wrapping up"
})
Shutdown Response (type "shutdown_response")
Teammate approves or rejects shutdown:
// Approve (terminates your process)
SendMessage({
type: "shutdown_response",
request_id: "shutdown-123",
approve: true
})
// Reject (continue working)
SendMessage({
type: "shutdown_response",
request_id: "shutdown-123",
approve: false,
content: "Still working on task #3, need 5 more minutes"
})
IMPORTANT: Extract the requestId from the JSON shutdown_request message and pass it as request_id. Simply saying "I'll shut down" is not enough -- you must call the tool.
Plan Approval (type "plan_approval_response")
Leader approves or rejects teammate's plan:
// Approve
SendMessage({
type: "plan_approval_response",
request_id: "plan-456",
recipient: "architect",
approve: true
})
// Reject with feedback
SendMessage({
type: "plan_approval_response",
request_id: "plan-456",
recipient: "architect",
approve: false,
content: "Please add error handling for the API calls and consider rate limiting"
})
TeamDelete -- Remove Team Resources
TeamDelete()
Removes:
~/.claude/teams/{team-name}/directory~/.claude/tasks/{team-name}/directory
IMPORTANT: Will fail if teammates are still active. Use shutdown_request first.
Task Tool -- Spawn Teammates
Task({
team_name: "my-project", // Required -- which team to join
name: "worker-1", // Required -- teammate's name
subagent_type: "general-purpose",
prompt: "Your instructions here...",
run_in_background: true // Teammates usually run in background
})
For spawning without team membership (subagents), see Skill(command: "swarm-spawning").
Message Formats
Messages are JSON objects stored in inbox files.
Regular Message
{
"from": "team-lead",
"text": "Please prioritize the auth module",
"timestamp": "2026-01-25T23:38:32.588Z",
"read": false
}
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"
}
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
}
Error Handling
Common Errors
- "Cannot cleanup with active members" -- Teammates still running. Send shutdown_request to all teammates first, wait for approval.
- "Already leading a team" -- Team already exists. Call TeamDelete first, or use different team name.
- "Agent not found" -- Wrong teammate name. Read
config.jsonfor actual names. - "Team does not exist" -- No team created. Call TeamCreate first.
- "team_name is required" -- Missing team context. Provide
team_nameparameter. - "Agent type not found" -- Invalid subagent_type. Check available agents with proper prefix.
Graceful Shutdown Sequence
Always follow this sequence:
flowchart TD
A[1. Send shutdown_request to all teammates] --> B[2. Wait for shutdown_response approve]
B --> C[3. Verify no active members in config.json]
C --> D[4. Call TeamDelete]
// 1. Request shutdown for all teammates
SendMessage({ type: "shutdown_request", recipient: "worker-1", content: "All tasks complete" })
SendMessage({ type: "shutdown_request", recipient: "worker-2", content: "All tasks complete" })
// 2. Wait for shutdown approvals
// Messages arrive automatically in your inbox
// 3. Verify no active members
// Read ~/.claude/teams/{team}/config.json
// 4. Only then cleanup
TeamDelete()
Handling Crashed Teammates
Teammates have a 5-minute heartbeat timeout. If a teammate crashes:
- They are automatically marked as inactive after timeout
- Their tasks remain in the task list
- Another teammate can claim their tasks
- TeamDelete will work after timeout expires
Debugging
Read team config to see members:
# Check team config -- view members and backend types
# Read ~/.claude/teams/{team}/config.json
# Check teammate inboxes
# Read ~/.claude/teams/{team}/inboxes/{agent}.json
# List all teams
# ls ~/.claude/teams/
# Check task states
# Read ~/.claude/tasks/{team}/*.json
Related Skills
- Core concepts --
Skill(command: "swarm-primitives") - Spawning agents --
Skill(command: "swarm-spawning") - Patterns and recipes --
Skill(command: "swarm-patterns")
SOURCE: Claude Code v2.1.45 tool descriptions (TeamCreate, SendMessage, TeamDelete) -- verified from system prompt 2026-02-18