Back Original

Message your other Claude Code sessions

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. To move a whole conversation or its context, resume the session instead. 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:

Use messaging between independent sessions that you start and steer yourself. Claude Code has a dedicated feature for each of the other ways to run or reach multiple sessions, so use the one built for what you’re doing instead:

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. To prompt one yourself, tell Claude what you want the other session to know or do. This example is a prompt you type, not a message Claude sends:

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:

For what the message Claude writes looks like when it arrives, including an example of one, see what a message looks like.

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. Between two ordinary interactive sessions with default settings, Claude Code delivers the message. Delivery isn’t guaranteed in every configuration, though. The receiving session checks each arriving message against its own inbound controls, and the check ends in one of three outcomes:

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. Claude is instructed never to ask another session for an action that was denied or blocked in its own session, or that its own permission settings would block, and to route that work back to you instead. On the receiving side, the receiving session’s own permission prompts and rules still apply to anything the message asks for.

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. The listing covers:

A session answers to the name you set with the /rename command or the --name flag. When you don’t set one, Claude Code names the session itself. An interactive session gets a name derived from its working directory’s folder name, such as myapp-3f. Two sessions can end up with the same name. The /list-agents output shows each local session’s working directory, which tells same-named sessions apart when they run in different directories. Claude’s own listing adds a short identifier to each row and uses it in the address when names collide.

Message sessions on other machines

Where the other session runs decides how a message travels and what Claude here can send:

Same-machine delivery works wherever the feature is enabled. Each session registers itself in files on disk and binds its inbox socket there. When Claude lists or messages your local sessions, Claude Code reads those files to find them, so two sessions can reach each other only when they can see the same files. A container has its own filesystem, so a session inside it and a session on the host can’t reach each other. Two sessions inside the same container can still message each other, including on a self-hosted runner. A reply needs a reply address, and almost every message carries one. A reply to a session beyond this machine, sent while the replying session isn’t connected to Remote Control, still goes through as a direct request to Anthropic servers, but it arrives without a reply address, so the receiver can’t answer it. Claude is told as much when it sends. To require your approval before any message goes beyond this machine, set isolatePeerMachines.

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:

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. A message is a piece of text one Claude writes to another. Claude receives it with the sender’s name and a reply address, except for a one-way cross-machine reply, which carries no reply address. You see the name and the text, and the receiving session gets only that text, never the sender’s conversation history or files. This example is a message one Claude wrote to another, as the receiving session sees it:

Control inbound messages

Set crossSessionInbound to choose what a session does with messages arriving from your other sessions:

To see which value applies, follow the crossSessionInbound precedence rules in the settings reference. When no value applies, Claude Code decides per message from the two sessions’ permission modes. It groups sessions that bypass permission prompts into one class, and every other session into the other. Plan mode counts as bypassing in sessions with bypass permissions available, and auto, acceptEdits, and dontAsk count as prompting:

When the default holds a message, Claude Code opens an approval dialog in the receiving session. The dialog shows the sender and a preview:

When the sender runs on the same machine, Claude Code tells the sending session what happened. A notice appears there when the message is held, and a follow-up reports the outcome when the receiver later delivers, denies, or expires it. A message refused on arrival produces no sender-side notice. Claude Code holds at most 100 messages, separately from the delivery queue, and past that drops the oldest.

Non-interactive sessions

Claude Code binds an inbox socket for a claude -p session like an interactive one, so a long-running -p worker can receive messages and appears in the listing. When you start a session in bare mode, Claude Code doesn’t bind the socket, so that session can’t receive messages and doesn’t appear in the agent list. A -p session can’t show the approval dialog. A held message stays held there. Claude Code delivers it only if a later mode or settings change allows it, under the same rules as above. To let a -p worker take messages unattended, start it with crossSessionInbound set to accept in its --settings value. An accept in your user settings also works but applies to every session you run.

The session’s inbox socket

Read this section when a session you expect isn’t in the agent list, when you want a script or hook to post into a session, or when a sandboxed command can’t reach the socket. Claude Code binds an inbox socket for each session with cross-session messaging enabled, where other sessions on the machine deliver messages. It restricts the socket to your operating-system user, so on a shared machine another user’s sessions can’t reach it. For which session kinds bind one, see Non-interactive sessions. You can find the path in two places:

Claude Code runs messages arriving on the socket through the same inbound controls as any other peer message, with one exception and one prerequisite:

Restrict cross-session messaging

Beyond the per-message defaults, you can narrow messaging in two ways. Require your approval before any message leaves the machine, or turn messaging off for a session or an organization.

Require approval for cross-machine messages

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

With this set, Claude Code asks for your approval before Claude’s reply to a session beyond this machine leaves, even in bypassPermissions mode, which skips ordinary permission prompts. A true from any settings scope applies, so a checked-in project file can turn the requirement on but not off. Messages between sessions on the same machine don’t prompt.

Turn off cross-session messaging

Receiving and sending are separate controls, so turn off whichever direction you need, or both. Use crossSessionInbound for messages that arrive, and permission rules for what Claude here can send or list:

Administrators can turn both sides off for an organization in managed settings, combining the deny rules with the refuse:

With this in place, Claude Code still binds each session’s inbox socket, but drops every message that arrives on it without delivering anything to Claude. Denying SendMessage also removes messaging to subagents and agent-team teammates, since the same tool serves both. A refusing session shows no visible change, in its own /status or in other sessions’ listings, so confirm the setting from the session’s configuration.

Availability

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

To check a session, type /list-agents, also available as /peers. The result separates a session that doesn’t have the feature from a session where something narrower blocked a message, such as a missing SendMessage tool or a refused send:

In a session with messaging, /status also shows a Peer address row with the session’s own inbox address.

Limitations

The limits here are properties of the messaging channel itself and apply wherever the feature runs. For platform and provider gaps, see Availability instead.