OmniscioGuidesClaude Code cross-session messaging
Claude Code cross-session messaging: what it does and how to control it
From 2.1.224 on macOS and Linux, and 2.1.234 on native Windows, one session can message another mid-task; on some providers, or with feature-flag fetching off, same-machine messaging needs 2.1.248. Claude finds targets with ListAgents and sends with SendMessage, so you never call either tool yourself.
This page covers what crosses the wire, what the other session sees, who decides delivery, and how to close it.
Written from Anthropic’s documentation as read on November 1, 2026, when the latest Claude Code release was 2.1.316. Not run by us. By the Omniscio team. Updated .
The short version
Cross-session messaging passes text between two running sessions: only text, never your history or files. The receiver decides what to do with each by its crossSessionInbound setting if one applies, otherwise by the two sessions’ permission modes.
What crosses between sessions
A message is text
A message is plain text one Claude writes for another, never history or files; resume the session to move a conversation.
Versions
It needs 2.1.224 or later on macOS and Linux, including Linux inside WSL 2, and 2.1.234 or later on native Windows. Once met, messaging is on with nothing to enable.
On Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform or Microsoft Foundry, or with feature-flag fetching off, same-machine messaging needs 2.1.248 or later.
Unasked sends
Claude can also send without being asked, for example after a change affecting what another session is building on.
It first shipped in Claude Code 2.1.224, in the release week of August 3 to 7, 2026, on macOS and Linux only.
What it is for
It is for hand-off: a session finds a breaking change and tells the one working on that area.
Two sessions on separate copies of a repository can say what landed, and a long migration can report back to the session you are watching.
Sending a message: naming the target
The simplest send is a sentence to the Claude in front of you: say what the other session needs and which it is. The prompt is yours; the wording is Claude’s, so identical prompts can differ.
Ask the session running in my other terminal whether the migration finished
Let @api-worker know the schema migration finishedNaming the target with @
An @ mention names the target and needs 2.1.232 or later. Type @ plus the first letters of a name, and a typeahead lists your other live sessions on this machine. Picking one inserts the mention, tells Claude which session it names, and skips the listing step.
A name with a space, or a character outside letters, digits, - and _, needs double quotes, such as @"release notes"; the picker adds them. Two live sessions with one name make Claude ask which you mean before sending.
A session answers to the name set with /rename or --name, else the one Claude Code gives it, which for an interactive session is its listing name.
Same-named sessions in different folders differ by working directory or a short identifier.
What Claude can reach
Run /list-agents, also /peers. The rows are:
- Subagents inside this session, and its agent-team teammates.
- Your other local sessions, including background ones.
- While connected to Remote Control: Anthropic’s cloud sessions, and your sessions on other machines.
Teammate rows, and the first line carrying this session’s own name, need 2.1.239 or later.
A local session appears only when it binds an inbox socket, so bare mode never shows up.
That socket is the per-session address others on that machine deliver to: a Unix socket, or a named pipe on native Windows.
While connected to Remote Control, the listing withholds three things:
- Local working directories.
- Names Claude Code cannot attribute to a person; such a row reads
(unnamed session). - This session’s own name line, unless you typed that name at this terminal.
What the receiving session sees
Arrival
Delivery waits for a pause: during a turn Claude reads it between tool calls, so a running tool finishes; an idle session gets a new turn.
The text is plain: an @ mention attaches nothing, whether it starts a turn or arrives during one. The receiving Claude can still open a mentioned path with its own tools, under that session’s permissions.
What you see
The message shows as a dim one-line preview that stays afterwards, with the sender’s name and a summary: the sender’s own, or the first line of the message.
For example: › Message from @api-worker: Schema migration finished (ctrl+o to expand).
Press Ctrl+O for the full text; in fullscreen, click a truncated preview; --verbose shows all of it. A busy session lists an unread message under Waiting to be delivered, from 2.1.309.
The preview shortens only what you see: Claude reads the full message.
What it can do
The receiver is told the message came from another session, not you. It never counts as approval or answers a permission prompt for you.
Claude is instructed never to change permission settings, CLAUDE.md or other configuration because another session asked.
A command in the text, such as /compact, arrives as plain text and never runs.
If acting on it needs a permission the session lacks, you see the usual prompt; boundaries stay per-session.
Delivered, it counts toward usage like a prompt you type.
The receiving Claude can reply with SendMessage unless messaging is off there, the receiver is a cloud session answering another machine, or there is no reply address (explained below).
Who decides delivery
The receiver checks every message and ends one of three ways: delivered, held, or refused and dropped. crossSessionInbound chooses; with no value, the two sessions’ permission modes decide.
| Value | What it does |
|---|---|
accept | Delivers each message to Claude. |
hold | Shows a notice, delivers nothing; a later accept releases them. |
refuse | Drops each message without delivering it. |
| No value applies | Decided per message by the two sessions’ permission modes (below). |
Setting it
Set it in a settings file, or in /config under Messages from your other sessions (written to user settings). The row needs 2.1.232 or later and hides while managed settings or --settings set the key.
Precedence: managed, --settings, user settings; refuse beats hold beats accept, and a project or local value applies only when stricter.
From 2.1.248 an unrecognised value warns and holds inbound messages even when a higher-precedence source says accept; another source’s refuse still applies.
In managed settings it counts as refuse until fixed. Before 2.1.248, Claude Code ignored an unrecognised value without any warning.
No value set
Claude Code decides per message from the two sessions’ permission modes. It groups sessions into two classes: those that bypass permission prompts, and every other.
Plan mode bypasses only in an interactive terminal with bypass permissions available; otherwise plan mode, auto, acceptEdits and dontAsk prompt.
In short, two sessions in the same class deliver the message, and two in different classes hold it for your approval. The sender declares whether it bypasses; approval happens at the receiver.
| With no value applying | Sender prompting | Sender bypassing |
|---|---|---|
| Receiver prompting | Delivered | Held for approval |
| Receiver bypassing | Held for approval | Delivered |
“Held” means two things: an explicit hold shows a notice and delivers nothing until an accept applies; the default waits for approval in the dialog below.
Approval dialogs
When the default holds a message in an interactive terminal session, an approval dialog opens there with the sender and a preview. Approve delivers it; Deny or dismissal drops it.
Unanswered, it closes and drops the message at the dialogExpiry deadline, five minutes by default. A background session with no terminal keeps it open until you attach and leave it unanswered a full period.
A permission-mode class change while messages are held re-applies the rules and delivers what they now accept.
Sessions that cannot show the dialog: a non-interactive claude -p, the VS Code extension, and the Desktop app. Each holds until the deadline, then drops; accept delivers instead.
At most 100 messages can be held at once; past that the oldest drops. The 50 under When a message doesn’t arrive counts accepted messages queued for Claude, so they differ.
Unattended workers
An unattended claude -p worker starts with crossSessionInbound set to accept in its --settings; an accept in your user settings also works, but it applies to every session you run.
dialogExpiry takes 60s, 5m, 10m or never. never keeps default-held messages until the session ends; an explicit hold never expires and is released by a later accept.
When the sessions are on different computers
Where the target runs decides the route and whether text touches Anthropic’s servers.
| Where the other session runs | How the message travels |
|---|---|
| On this machine | Over a per-session socket on macOS and Linux, or a named pipe on native Windows. Never through Anthropic servers. |
| On another of your machines | Through Anthropic servers, arriving over that machine’s Remote Control connection. |
| In the cloud | Through Anthropic servers, straight to the cloud session. |
Finding a session beyond this machine needs Remote Control connected, which requires a claude.ai account; an API key cannot find them elsewhere. A conversation with another machine takes 2.1.225 or later and a target in the listing.
A row beyond this machine can also carry a condition. offline means its Remote Control connection dropped: the message arrives on reconnect.
can't receive cross-session messages means messaging is off there or its crossSessionInbound is refuse: the send is refused before it leaves your machine, and the SendMessage result begins Not sent.
An Anthropic cloud session cannot use SendMessage to answer a message from another machine, even with a reply address, so read its answer at claude.ai/code.
Without Remote Control here, a cross-machine message still goes but carries no reply address, so the receiver cannot answer.
The notice when a session finishes
To be told when a long task ends, say what you are waiting on, such as tell me when the migration session finishes. Claude subscribes with the notify_when_idle input of SendMessage, alone or attached to a message.
Alone, it starts no turn, spends no tokens in the watched session, and an already-idle session answers at once. It needs 2.1.236 or later in both.
Idle means a turn finished with nothing queued. The watched session shows that another process asked for a notice; the asker shows a line naming it, which can carry the turn’s finish time and a one-line status.
An idle asker starts a new turn on the notice.
Three limits. No notice inside 12 hours drops the subscription, so Claude stops waiting.
Inbound controls apply: refuse on either side means nothing arrives and the subscription expires unanswered, while hold means a thinner notice, without the one-line status, shown to you but not delivered to Claude.
Only the Claude in your main conversation can subscribe, and only to your sessions on this machine; any other target, teammate, subagent or other machine, is refused as a whole call, with any attached message.
Turning it off, one way or both
Receiving and sending are separate. Receiving off is crossSessionInbound set to refuse, also in /config under Messages from your other sessions. Sending off is a pair of permission deny rules:
{
"permissions": {
"deny": ["SendMessage", "ListAgents"]
},
"crossSessionInbound": "refuse"
}Both take the bare tool name, no specifier, in a settings file. A refuse in project or local settings beats every other source. In user settings it holds unless managed settings or --settings set a value.
See the settings guide for file precedence.
In managed settings the same entries close messaging for the whole organisation: sockets are still bound, but everything arriving is dropped. Denying SendMessage also removes subagent and teammate messaging.
A refusing session looks unchanged in its own /status and in the listings of other sessions on the same machine, so check the settings files.
On another machine or in the cloud it shows as can't receive cross-session messages.
isolatePeerMachines set to true asks your approval before any cross-machine message leaves, even in bypassPermissions, and never prompts for same-machine messages. Any file’s true applies, so a project file can turn it on but not off.
When a message doesn’t arrive
Start with /list-agents. If the session does not recognise the command at all, it lacks the feature, and the fix is a version check: run claude --version.
If the command works but a send vanished, find your row below; with no settings changed and the target listed, start with “You changed no settings”.
The symptom table
| What you see | What it means | What to do |
|---|---|---|
| Claude cannot send or list | A deny rule on SendMessage or ListAgents removed the tools | Check the sending session’s deny rules |
A session on this machine is missing from /list-agents | It has no inbox: it started in bare mode, or Claude Code could not set one up (its /status shows unavailable and the reason under Peer address) | Start it without bare mode, or act on its /status reason |
A cloud or other-machine session is missing from /list-agents | This session is not connected to Remote Control (those rows need it), or the other machine’s session is not running it | Connect Remote Control here and, for another machine, there too |
| An older cloud or other-machine session is missing | Those lists read newest first and stop after a bounded number of pages | Message a more recent session, or ask from the other side |
A row for another machine says offline | That machine’s Remote Control connection dropped | Wait; it arrives when it reconnects |
A row for a session on another machine or in the cloud says can't receive cross-session messages | Messaging is unavailable there, or its inbound setting is refuse | Change it in that session; the refusal names the reason |
| You changed no settings, the target is listed, and the message did not arrive | If the two sessions are in different permission-mode classes, the receiving session held the message and opened an approval dialog. In an interactive terminal session an unanswered dialog closes after five minutes (the default dialogExpiry) and the message is dropped; a background session keeps it open while no terminal is attached | Approve it there; after five minutes, put both sessions in one class and resend. Who decides delivery explains the rule |
The same, and the receiver is a claude -p session, the VS Code extension or the Desktop app | These cannot show the dialog, so a message from the other class waits until the deadline and is dropped | Set crossSessionInbound to accept in its user settings or, for a claude -p worker, its --settings; that delivers from every sender, and a user-settings value applies to every session you run |
The receiving session has a crossSessionInbound value set | An explicit hold shows a notice and delivers nothing until an accept applies; refuse drops each message | Check its /config row and settings files |
| Both sessions are on one computer, and a send never arrives or the target never appears | A container session and a host session cannot reach each other, though two in one container can; a session inside WSL 2 and a native Windows session cannot either | Run both in the same environment |
Claude’s SendMessage result says refused, or Claude Code reports it dropped | The messaging path refused it (too large, too fast, or a target Claude Code could not confirm), or the recipient’s inbox dropped it | See the paragraphs under this table |
Refused before it leaves
The path refuses some messages before they leave, in the tool result. A same-machine message over about a million characters is refused, and the refusal gives the message’s size and the limit.
A rapid burst past what that inbox accepts is refused, with advice to batch or wait.
A send is also refused when Claude Code cannot confirm the target’s inbox, as with a symlink.
Dropped after it was sent
After sending, the recipient’s inbox can drop a message. Claude Code names the recipient and, if the recipient supplied reasons, one of four:
- its undelivered queue was full
- the sender sent faster than that session accepts
- it repeated an earlier message
- a relay loop was cut
Repeats are rate-limited per sender, identical repeats in a short window are dropped, and 50 accepted messages queue. If it matters, send one combined message later.
Older builds
Before 2.1.235 an oversized message was reported sent and dropped unread; before 2.1.236 a burst at the limit was the same; before 2.1.238 the sender heard nothing when the inbox discarded it.
Where this page stops
- Work inside one session or one team. Subagents and teammates use the same
SendMessage, but messaging within a session or team is separate, and agent-team structured messages stay in the team. The subagents guide covers them. - Events from outside. A channel pushes external events, such as CI results or chat messages, into a session: the opposite direction, owned by the channels guide.
- Running many sessions. Background sessions, the agent view and dispatching belong to background tasks and running several sessions.
- Reaching another machine. The connection and its failures belong to the Remote Control guide; this page uses it only as the road.
Omniscio, and the same idea over a different wire
Omniscio runs many Claude Code sessions, so it needs the same ability, and it has its own: one session posts a message to another over the app’s local control server, and the target can be woken.
The two features are separate. Claude Code’s talks to another running Claude Code session; Omniscio’s talks to another app session, including a stopped one.
- A message becomes a turn.
POST /sessions/:id/peer-messageinjects an operator turn and returns while the target works. The turn is tagged as injected, and the receiver is told it came from another session; it can fold the exchange into one collapsible line. Omniscio’s cross-session messaging page covers the addresses, wake rules and reply path. - Do Not Disturb has four states:
off,no-interrupt,hold-all,block.no-interruptholds a mid-turn message until the turn ends;hold-allalso stops one starting a turn on an idle session. Both govern when;blockalone governs whether, refusing agent messages while your own and system notices still arrive, and only a person can set it. Block agent messages covers blocking versus hiding. - Sends are rate-limited: 120 messages an hour per sender, with a larger allowance for an operator-designated coordinator, and the refusal says when to retry.
- A broadcast reaches a whole project: one message goes to every live agent in the sender’s project at once.
Session-to-session talk is this page’s feature and needs no app; Omniscio adds visibility, waking and blocking.
Sources
Every Claude Code behaviour here rests on one of these, read on the date beside it.
- Message your other Claude Code sessions, for the minimum versions, what a message is, delivery, the inbound controls, the transport table, the idle notice, the limits and the ways to turn it off. Read November 1, 2026.
- Settings reference, for
crossSessionInboundand its precedence,dialogExpiryand its values, andisolatePeerMachines. Read November 1, 2026. - Tools reference, for the
ListAgentsandSendMessagerows, including the optional summary input. Read November 1, 2026. - Commands, for
/list-agentsand its/peersalias. Read November 1, 2026. - Errors, for the refusals a sender sees: message too large, too many messages just now, dropped at the recipient’s inbox, and refusing to send. Read November 1, 2026.
- Remote Control, for the claude.ai sign-in requirement and the API-key limitation. Read November 1, 2026.
- Permissions, for the bare tool-name form a deny rule takes. Read November 1, 2026.
- Interactive mode, for the transcript viewer that
Ctrl+Oopens. Read November 1, 2026. - Sessions, for the names a session answers to in listings of running sessions. Read November 1, 2026.
- What’s new, week 32 of 2026, for the feature’s first release, 2.1.224, and the platforms it launched on. Read November 1, 2026.
- Omniscio’s own cross-session messaging page and block agent messages page, read on November 1, 2026, and the Omniscio source files they describe.
- Two checks we made on November 1, 2026: the npm registry’s latest version for
@anthropic-ai/claude-code, and the HTTP status of each documentation page read in its Markdown form.
Minimum versions appear in almost every paragraph, and two refusals used to report success; treat the version at the top of this page as the one these statements describe.
How we tested this
Every Claude Code statement here was read from Anthropic’s documentation on November 1, 2026, in the Markdown form the site serves, on the pages named in Sources; the release checked is 2.1.316.
No sessions were started, no settings edited and no message sent, so this is Anthropic’s account, not our own run. Omniscio’s statements came from those library pages and source files.
Common questions
Can Claude Code sessions message each other?
Yes, from Claude Code 2.1.224 on macOS and Linux, including Linux inside WSL 2, and from 2.1.234 on native Windows; on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry, or with feature-flag fetching off, same-machine messaging needs 2.1.248 or later. Claude finds a target with the ListAgents tool and sends with the SendMessage tool, and you never call either of them yourself: you ask in plain language, or Claude decides on its own that another session needs to know something. A message is text one Claude writes for another, never the sender's conversation history or its files.
How do I send a message to another Claude Code session?
Tell Claude what the other session needs to know and which session it is, for example: let @api-worker know the schema migration finished. The @ mention needs Claude Code 2.1.232 or later and saves Claude the listing step; without it Claude finds the target itself. Naming a session with /rename or --name makes addressing it easier, and to see what Claude can reach yourself, run /list-agents, also available as /peers.
Why did my message to another session not arrive?
Check four things. The receiving session's crossSessionInbound setting can hold a message or refuse it outright. With no value applying, the permission modes of the two sessions decide: when they sit in different classes the receiving session asks for approval, and an interactive terminal session drops a message nobody approves after five minutes by default. A permission deny rule on SendMessage or ListAgents removes the tools that send and list. A session beyond this machine appears in the listing only while this session is connected to Remote Control, and a session on another machine must be running it too. And the messaging path itself refuses an oversized message and a rapid burst before they leave the sender, while a repeat of an earlier message is dropped at the receiving end and reported back.
How do I stop other sessions messaging mine?
Set crossSessionInbound to refuse, in a settings file or in /config under Messages from your other sessions, and the session drops inbound messages without delivering them. Separately, permission deny rules naming SendMessage and ListAgents stop a session sending or listing. A refusing session looks unchanged in /status and in the listings of other sessions on the same machine, so confirm it from the settings files that apply rather than from the session's status.
Can a Claude Code session message one on another machine?
Yes. To find a session beyond your machine, this session must be connected to Remote Control with a claude.ai account (an API key cannot find sessions beyond your machine), and a session on another machine must be running it too. Messages to another machine or to a cloud session travel through Anthropic servers, while two sessions on this machine use a local socket or named pipe and never leave the computer. A cloud session cannot use SendMessage to answer a message from another machine, so you read its answer in its transcript at claude.ai/code.
When two sessions are not enough
Omniscio runs Claude Code sessions side by side in one window with the same idea: sessions message each other, a stopped one can be woken, only you can close a session to agents, and a broadcast reaches a whole project.
The features page covers the rest; download it for Windows, macOS or Linux. The subagents and channels guides cover the neighbours.