Cross-session messaging requires Claude Code v2.1.224 or later and runs on macOS and Linux. When a session meets the requirements, messaging is on with nothing to enable. Cross-session messaging lets Claude deliver a message from one of your Claude Code sessions to another. When a change in one session breaks what another is building on, Claude can warn that session before you notice. When one session settles a question another is blocked on, Claude can send the answer across. A message is a piece of text one Claude writes to another, never conversation history or files.

Claude uses two tools for this: ListAgents to discover which agents it can reach, and SendMessage to deliver a message to one of them by name. With the same SendMessage tool, Claude can also message subagents and agent team teammates within a single session or team. This page covers messages between your independent sessions.

When to use cross-session messaging

Use messaging when one of your sessions has something another session needs mid-task. Claude can send a message on its own when it sees the need, for example after making a change that affects work another session is doing, or you can ask it to send one. The common cases:

• Hand over a finding: when one session discovers a breaking change or makes a decision, Claude summarizes it for the session working on the affected area, instead of you re-explaining it there.
• Coordinate parallel worktrees: when sessions work the same repository in separate worktrees, Claude can tell the other sessions what landed.
• Get status from long-running work: have a migration or test run report back to the session you’re watching, or ask it yourself from there.
• Message across machines: reach one of your sessions on another machine or on the web.

Use messaging between independent sessions that you start and steer yourself.

Message another session

When one of your sessions learns something another session needs, such as a finding, a status, or a decision, Claude passes it along instead of you copy-pasting between terminals. Claude discovers the target with ListAgents and sends with SendMessage, so you never call either tool yourself. Claude can decide to send a message without being asked, and you can also prompt for one.

Ask the session running in my other terminal whether the migration finished

Claude writes the actual message itself, so your prompt can leave the content to Claude. This prompt asks for a summary without dictating its wording, and what Claude sends varies:

Explain what we just did to the session working on the payments API

Message delivery

The receiving Claude reads the message between tool calls during an active turn, so a running tool is never interrupted. When the receiving session is idle, Claude Code starts a new turn with the message. The receiving session checks each arriving message against its own inbound controls, and the check ends in one of three outcomes:

• Delivered: Claude Code passes the message to the receiving Claude.
• Held: Claude Code sets the message aside undelivered. A held message reaches Claude only when you approve it or a later mode or settings change allows it.
• Refused: Claude Code drops the message without delivering it.

Once delivered, the message counts toward usage like a prompt you type, and the receiving Claude can reply to the sender the same way, except in the one-way cross-machine case. Permission boundaries stay per-session.

See which sessions Claude can reach

Claude finds a message’s target on its own, so you don’t need to run anything before asking it to send. To see for yourself which sessions Claude can reach, run the /list-agents command. It lists each session with the name it answers to, and that name is where Claude addresses a message.

Message sessions on other machines

How a message travels, and whether it passes through Anthropic servers, depends on where the target session runs:

How a session treats an incoming message

When session A messages session B, Claude Code tells B’s Claude that the message came from another session, not from you, and limits what the message can do:

• It can’t approve anything: a message from another session never counts as your consent, so it can’t answer a pending permission prompt on your behalf.
• It can’t change configuration: Claude Code instructs the receiving Claude never to change permission settings, CLAUDE.md, or other configuration because another session asked.
• Commands don’t run: a command in the message’s text, such as /compact, arrives as plain text. Claude Code never executes it.
• Permission prompts still fire: if acting on the message requires a permission the receiving session doesn’t have, you see the same prompt you’d see for any other work.

What a message looks like

When the message arrives, it appears in the conversation with its sender, queued while Claude is mid-turn or starting a new turn right away when the session is idle. Once Claude has read it, Claude Code collapses it to a one-line Message from row, which Ctrl+O expands.

Control inbound messages

Restrict cross-session messaging

Require approval for cross-machine messages

Set isolatePeerMachines to true to require your explicit approval before any SendMessage reaches a session beyond this machine.

Turn off cross-session messaging

Receiving and sending are separate controls, so turn off whichever direction you need, or both.

Availability

Cross-session messaging requires Claude Code v2.1.224 or later. Availability also depends on your platform, provider, and configuration:

• Operating system: available on macOS and Linux, including Linux inside WSL 2.
• Provider: not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry.

Limitations

• Plain text only: Claude sends only plain text across sessions.
• Message loops are throttled: Claude Code rate-limits repeated messages per sender, drops identical repeats arriving within a short window, and caps accepted messages waiting for Claude to read them at 50 per session.