messaging

name	messaging
description	Send messages between agents using SendMessage including direct messages, broadcasts, shutdown requests/responses, and plan approvals. Use when communicating between agents, understanding message formats, or handling structured protocol messages.

Messaging

Experimental: Agent teams are disabled by default. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in your settings.json or environment.

Send and receive messages between agents. All inter-agent communication flows through the messaging system.

Related skills:

• Orchestrating - Primitives overview and quick reference
• Team Management - Shutdown and plan approval workflows
• Task System - Coordinating task progress
• Error Handling - Debugging message issues

---

SendMessage Tool

All messaging uses the SendMessage tool. The to field specifies the recipient and the message field carries either a plain string or a structured protocol object.

Direct Message

Send a message to one specific teammate:

SendMessage({
  to: "security-reviewer",
  message: "Please prioritize the authentication module. The deadline is tomorrow.",
  summary: "Prioritize auth module review"  // 5-10 word preview shown in UI
})

Parameters:

• to - Teammate name (required)
• message - Message text (required)
• summary - Brief preview for UI (required)

IMPORTANT for teammates: Your plain text output is NOT visible to the team. You MUST use SendMessage to communicate. Just typing a response is not enough.

Broadcast

Send the same message to all teammates at once:

SendMessage({
  to: "*",
  message: "Status check: Please report your progress",
  summary: "Requesting status from all teammates"
})

WARNING: Broadcasting is expensive. Each broadcast sends N separate messages for N teammates. Costs scale linearly with team size.

When to broadcast:

• Critical issues requiring immediate team-wide attention
• Major announcements that affect everyone equally

When NOT to broadcast (use direct message instead):

• Responding to one teammate
• Normal back-and-forth communication
• Information relevant to only some teammates
• Following up on a task with one person

Shutdown Request

Ask a teammate to gracefully exit:

SendMessage({
  to: "security-reviewer",
  message: { type: "shutdown_request", reason: "All tasks complete, wrapping up" }
})

Shutdown Response

When you receive a shutdown request, you MUST respond:

Approve (exits your process):

SendMessage({
  to: "team-lead",
  message: { type: "shutdown_response", request_id: "shutdown-abc123", approve: true }
  // request_id comes from the shutdown_request message
})

Reject (continue working):

SendMessage({
  to: "team-lead",
  message: { type: "shutdown_response", request_id: "shutdown-abc123", approve: false, reason: "Still working on task #3, need 5 more minutes" }
})

IMPORTANT: Extract the requestId from the received shutdown request JSON and pass it as request_id. Simply saying "I'll shut down" is NOT enough - you must call the tool.

Plan Approval Response

When a teammate with plan_mode_required sends a plan approval request:

Approve:

SendMessage({
  to: "architect",
  message: { type: "plan_approval_response", request_id: "plan-xyz789", approve: true }
  // request_id comes from the plan_approval_request message
})

Reject with feedback:

SendMessage({
  to: "architect",
  message: { type: "plan_approval_response", request_id: "plan-xyz789", approve: false, feedback: "Please add error handling for the API calls and consider rate limiting" }
})

After approval, the teammate automatically exits plan mode and proceeds with implementation. If rejected, the teammate stays in plan mode, revises based on feedback, and resubmits.

---

Automatic Message Delivery

Messages from teammates are delivered automatically. You do NOT need to poll for updates.

When teammates send messages:

• They appear automatically as new conversation turns (like user messages)
• If you're busy (mid-turn), messages are queued and delivered when your turn ends
• The UI shows a brief notification with the sender's name when messages are waiting

---

Direct Teammate Interaction

You can interact with teammates directly without going through the lead:

• In-process mode: Use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.
• Split-pane mode: Click into a teammate's pane to interact with their session directly.

---

Idle Notifications

When a teammate finishes and stops, they automatically notify the lead. This is normal behavior - idle simply means they are waiting for input.

Key points:

• Idle teammates can receive messages. Sending a message wakes them up.
• Do not treat idle as an error. A teammate sending a message and then going idle is the normal flow.
• When a teammate sends a DM to another teammate, a brief summary is included in their idle notification for visibility.

---

Message Formats

Messages are JSON objects stored in inbox files at ~/.claude/teams/{team}/inboxes/{agent}.json.

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
}

---

Debugging Messages

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

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