How Claude Code Sessions Message Each Other

What cross-session messaging is

Claude Code sessions can now pass messages to each other. If you have two sessions open, one working through a database migration and one building the API that depends on it, the migration session can tell the API session the moment it finishes, without you copying anything between terminals yourself. This shipped in Claude Code v2.1.224, in the week of 3 to 7 August 2026, the same release that made auto mode the default permission mode and introduced self-hosted runners. Anthropic's cross-session messaging documentation and the Week 32 changelog are the sources this article is verified against.

The mechanism is two tools working together: ListAgents, which discovers which of your other sessions Claude can currently reach, and SendMessage, which delivers a message to one of them by name. You never call either tool directly, Claude decides to use them, either because you asked or because it noticed something the other session needs to know.

How Claude finds and reaches another session

A message is deliberately narrow: it's a piece of text one Claude writes for another, never your conversation history, never files. To move a whole conversation, including its context, resuming the session is the right tool instead, not messaging.

To prompt a message yourself, just describe what you want the other session to know:

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

Or leave the wording to Claude entirely:

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

To name a specific target, type @ followed by the first letters of a session's name and pick it from the typeahead, the same interaction as @-mentioning a subagent. This requires Claude Code v2.1.232 or later:

Let @api-worker know the schema migration finished

A session answers to whatever name you gave it with /rename or the --name flag, or, if you never set one, a name Claude Code derives itself, typically the working directory's folder name. Run /list-agents (aliased /peers) at any point to see exactly which sessions Claude can currently reach: subagents inside the current session, your other local sessions on the same machine, and, when this session is connected to Remote Control, your cloud sessions and sessions on your other machines.

What happens when a message is sent

The receiving Claude reads a message between tool calls during an active turn, so a running tool is never interrupted, or starts a fresh turn if the session is idle. Whether it actually gets delivered depends on the receiving session's inbound rules, and there are three outcomes:

• Delivered: Claude Code passes it straight to the receiving Claude.
• Held: Claude Code sets it aside and shows an approval dialog; it reaches Claude only if you approve it, or a later settings change permits it.
• Refused: Claude Code drops it without ever showing it to the receiving Claude.

Once delivered, a message counts toward usage the same as anything you type yourself, and the receiving Claude can reply, except in the one-way cross-machine case described below. Permission boundaries stay strictly per-session: Claude Code instructs the receiving Claude never to act on a request another session's own permissions would have blocked, and routes that back to you instead.

When it arrives, a message appears in the conversation tagged with the sender's session name, for example:

Schema migration finished: the new column is tenant_id, and rebasing on main is safe now.

Controlling inbound messages

crossSessionInbound is the setting that decides what a session does with messages from your other sessions:

You can also set this from /config, under Messages from your other sessions, which requires v2.1.232 or later and only appears when no managed setting or --settings flag already controls the key.

When nothing sets crossSessionInbound explicitly, Claude Code decides per message based on both sessions' permission modes. Sessions in bypassPermissions mode form one class; everything else, including auto, acceptEdits, and dontAsk, forms the other:

• A prompting receiving session delivers everything, and only holds a message for approval if the sender identifies itself as bypassing permissions.
• A bypassing receiving session holds everything for your approval, delivering only when the sender is also bypassing.

An unanswered approval dialog closes and drops the message once dialogExpiry passes, five minutes by default, unless the session is a background session with no terminal attached, in which case Claude Code leaves it open. Claude Code holds at most 100 messages at a time, dropping the oldest past that cap.

Messaging sessions on other machines

Where the target session runs determines how the message physically travels:

Same-machine delivery needs no configuration beyond having the feature available, each session registers itself in files on disk and binds an inbox socket there. Two sessions inside the same self-hosted runner container can message each other the same way; a session inside a container and one on the host cannot, since they don't share a filesystem. Starting a fresh conversation with a session on another machine (rather than only replying to one) requires v2.1.225 or later.

To require your explicit approval before any message leaves the current machine, regardless of mode:

{
  "isolatePeerMachines": true
}

What a receiving session can't do with an incoming message

Anthropic's documentation is specific about the limits placed on an inbound message, and they're worth knowing before relying on this for anything sensitive:

• It can't approve anything. A message from another session never counts as your consent and can't answer a pending permission prompt.
• It can't change configuration. The receiving Claude is instructed never to modify permission settings, CLAUDE.md, or anything else because another session asked.
• Commands inside the text don't run. Something like /compact embedded in a message arrives as plain text, Claude Code never executes it.
• Permission prompts still apply. If acting on a message needs a permission the receiving session doesn't already have, the same prompt fires as it would for anything else.

How this differs from subagents, agent teams, and Remote Control

SendMessage is the same tool Claude uses to message subagents and agent team teammates within a single session, this page covers the case of messaging between your independent sessions specifically. Anthropic's own guidance draws a clear line between these features, and it's worth keeping straight:

• To continue one conversation elsewhere, or hand its full context to a new session, resume the session, not messaging.
• For a coordinated team of sessions Claude itself spawns and supervises, use agent teams.
• To watch and steer many sessions from one place, use agent view.
• To steer a session yourself from your phone, use Remote Control, not cross-session messaging.
• To push external events like CI results into a session, use channels.

Cross-session messaging is specifically for sessions you started and steer independently, where one has learned something the other needs mid-task.

Availability and requirements

Cross-session messaging requires Claude Code v2.1.224 or later, plus:

• Operating system: macOS and Linux, including Linux inside WSL 2. Not available on native Windows.
• Provider: unavailable on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry.
• Feature-flag traffic: turned off if CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK disables the feature-flag evaluation the feature depends on.

There's nothing to opt into beyond meeting the requirements, messaging is on by default the moment a session qualifies.

Two hard limits worth knowing

• Plain text only. Claude never sends structured data across sessions this way; agent-team protocol messages stay inside their team.
• Loops are throttled automatically. Claude Code rate-limits repeated messages from the same sender, drops identical repeats arriving in a short window, and caps a session's queue of unread accepted messages at 50, so a message loop between two sessions stops on its own rather than running away.

Troubleshooting

/list-agents isn't recognised at all. The session doesn't have the feature. Start with claude --version to confirm you're on 2.1.224 or later, then check the operating system and provider requirements above.

/list-agents works, but a message never arrived. Something narrower is blocking it: a permission deny rule on SendMessage or ListAgents, the receiving session's crossSessionInbound setting holding or dropping it, or, for a cloud or other-machine session, the fact that it only appears in the listing while this session is connected to Remote Control.

Messages to another machine seem to go nowhere. Confirm this session is connected to Remote Control. If it isn't when Claude sends to a session beyond this machine, the message still goes through, but without a reply address, so the receiving Claude can't answer it.

An org wants to turn this off entirely. Combine a deny rule with a refuse setting in managed settings:

{
  "permissions": {
    "deny": ["SendMessage", "ListAgents"]
  },
  "crossSessionInbound": "refuse"
}

Each session still binds its inbox socket under this configuration, it just drops everything that arrives without ever showing Claude anything.

Where to go next

For the permission model governing what a session (and a message reaching it) is allowed to do, see Claude Code's auto mode explainer. For running sessions on your own infrastructure, the other headline feature from the same release, see how to self-host Claude Code runners. If you're new to Agent Skills generally, What Are Agent Skills? and How to Install Skills in Claude Code are good background. Browse the current Claude Code catalog at getclaudeskills.com/platforms/claude-code, or everything cataloged at getclaudeskills.com/skills.