Cross-Session Messaging in Claude Code

Since v2.1.224, every interactive Claude Code session on a Mac or Linux box binds a Unix socket at startup, and any other session you run can drop a text message into it; mine sits at /tmp/cc-socks/38590.sock, with owner-only permissions.¹ Native Windows gets a named pipe instead, since v2.1.239 by the release notes, and one late-bind exception sits under The Traps. Two tools drive the feature: ListAgents discovers which of your sessions are reachable, and SendMessage delivers to one of them by name.² Nothing to enable, nothing to configure. If both sessions run v2.1.224 or later (v2.1.239 on Windows) on the same machine, they can already talk.

TL;DR

Claude Code sessions can now message each other: on one machine over local sockets that never touch Anthropic’s servers, and across machines through Remote Control (reply-only at launch; v2.1.225 added the ability to start those conversations by name).¹⁵ A message is plain text only, never conversation history, files, or permissions, and the receiving session treats it as input, not authority: it cannot approve prompts, change configuration, or execute commands.¹ The feature turns a fleet of independent terminals into something closer to a team, and the best uses are coordination messages you used to ferry by hand: “the migration finished,” “I renamed that column,” “main is safe to rebase.” The sharpest trap is silent absence: four unrelated privacy environment variables can each quietly disable the feature, depending on their values.³ Since launch, Windows joined natively in v2.1.239, and v2.1.236 added notify_when_idle, which lets a session ask a same-machine peer for one notice when it next goes idle or exits.⁹¹⁰

What Shipped

The v2.1.224 release added cross-session SendMessage with ListAgents discovery on macOS and Linux; v2.1.225 extended it so a session can also start a conversation with your Remote Control sessions on other machines, where previously it could only reply.⁴⁵

Three surfaces let you see the machinery:

• /list-agents (alias /peers) prints the session’s own name on its first line (the name your other sessions use to reach it, shown since v2.1.239), then every session Claude can reach: subagents inside the current session, the session’s live agent-team teammates (listed since v2.1.239; before that a reachable teammate looked absent), your other local sessions including background ones, and, while Remote Control is connected, your sessions on other machines and on Claude Code on the web.¹⁹
• /status shows a Peer address row with the session’s own inbox socket, prefixed uds:.¹
• CLAUDE_CODE_MESSAGING_SOCKET, which Claude Code exports to hooks and Bash commands once the inbox is bound (see the late-bind note under The Traps), holds the session’s own socket path.¹⁶ More on why that matters below.

Verifying on my own machine on August 25, 2026, with Claude Code 2.1.246: the agent listing opened with the line “This session is blakecrosley-com-76 [04e18a] — the name other sessions use to message it (it is not listed below; a message to it would be a message to yourself).”, then 11 peer sessions as rows like “resumegeni-25 [10d770] · interactive · idle · started 21h ago”, names in the directory-plus-two-character-suffix form with a bracketed short identifier, states of idle, busy, and shell, a start age per row, and a separate Subagents block for the session’s own children. The socket files under /tmp/cc-socks/ carry srw------- permissions and the directory itself is drwx------: readable and writable by my user alone, which is the boundary on shared machines.¹

Sessions answer to names. Set one with /rename or the --name flag; otherwise Claude Code derives one from the working directory, like my-app-3f.¹¹¹ Since v2.1.232, when you start, resume, or rename an interactive session into a name another live session on the machine already uses, Claude Code leaves the name with the session that has it, renames yours to a name-word-word variant (something like auth-refactor-graceful-unicorn), and tells you.¹¹⁰ Collisions survive when one session runs an older version, when the shared name is one Claude Code generated, or when you start a background or -p session with a --name Claude Code doesn’t check at startup.¹¹ The listing always shows each local session’s working directory, which tells same-named sessions apart when they run in different directories; for a shared name Claude also adds a short identifier to each row and uses it in the address. Claude falls back to the same short-identifier addressing when Claude Code couldn’t check everywhere your sessions run, such as an account whose cloud or Remote Control session list ran past the bounded page count it reads.¹

What Changed Since Launch (August 2026)

Five releases in the two weeks after launch closed the Windows gap this post flagged, tightened naming and addressing, and closed four silent-failure modes the post did not flag:⁹¹⁰

Release	Change
v2.1.232	Unique names and @-mentions. Interactive sessions on one machine keep unique names (a collision renames the newcomer to a name-word-word variant and tells you); typing @ in the prompt mentions another live session by name, and Claude reaches it with SendMessage directly; /config gains a “Messages from your other sessions” row that writes crossSessionInbound (accept, hold, refuse) to user settings, alongside a “Dialog expiry” row. The same release hardened the auto-generated socket directory on shared /tmp: Claude Code now refuses a pre-planted symlink or another user’s directory instead of using it.110
v2.1.235	SendMessage refuses a message too large for cross-session delivery up front, instead of silently dropping it.10
v2.1.236	notify_when_idle: ask another session on the same machine to send one notice when it next goes idle or exits (both sessions v2.1.236+). Opt-in, one-shot, no polling. The same release refuses further messages up front once a rapid burst would exceed what the recipient’s inbox accepts, instead of reporting them sent while the recipient dropped them.110
v2.1.238	Delivery honesty: sending to a session on this machine that refuses inbound messages (crossSessionInbound: "refuse") now reports “refused” to the sender instead of a silent success, and a session whose inbox drops your messages (rate limit or full queue) tells your session instead of the messages vanishing.10
v2.1.239	Windows. Cross-session messaging works natively, with the same SendMessage and ListAgents tools; ListAgents now tells a session its own name (the one peers use to reach it) and lists live teammates, which previously looked absent; SendMessage to your own name says so instead of “no agent named …”.9

The practical effect: the “reporting long-runner” pattern below no longer needs a check-in prompt. The watching session asks the long-runner for one idle notice with notify_when_idle and hears back when the long-runner next goes idle or exits. Two of the four failure modes (a message too large, or a burst too fast for the inbox) now fail up front at the sender; the other two (a refused or dropped message) come back to an interactive same-machine sender as explicit reports.

The Trust Model Is the Interesting Part

Anthropic’s design answers a question most multi-agent systems fumble: what is a message from another agent worth? The answer here is precise: a message is information, never authority.¹

When session A messages session B, four rules bind what arrives:¹

1. It cannot approve anything. A pending permission prompt in B ignores anything A says. Only you answer prompts.
2. It cannot change configuration. Claude Code instructs the receiving Claude never to alter permission settings, CLAUDE.md, or any configuration because another session asked.
3. Commands arrive as text. A /compact in the message body is eight characters of prose, never an executed command.
4. Permission prompts still fire. If acting on the message needs a permission B lacks, you see the same prompt as for any other work.

Inbound delivery has its own gate. Each arriving message ends in one of three outcomes (delivered, held for your approval, or refused), controlled by the crossSessionInbound setting (accept, hold, refuse).¹ When you set nothing, Claude Code decides per message using the two sessions’ permission modes, and the default logic is elegant: sessions that bypass permission prompts form one class, everyone else the other (plan mode counts as bypassing when the session has bypass available; auto, acceptEdits, and dontAsk count as prompting). A prompting session receives messages freely but holds anything arriving from a bypassing session; a bypassing session holds everything except messages from fellow bypassing sessions.¹ The asymmetry is deliberate: a message must not ride a permissive session’s authority, a principle v2.1.224 applies inbound after v2.1.222 applied it outbound in auto mode, where the permission classifier reviews each send before dispatch.⁷

Held messages open an approval dialog showing sender and preview; unanswered dialogs expire after five minutes (tunable via dialogExpiry) and the message drops.¹ A background session with no terminal attached keeps the dialog open past that deadline; once you attach, the message drops only if the dialog stays unanswered for a full deadline period.¹ At most 100 messages hold at once.¹ Two more controls narrow things further: isolatePeerMachines: true requires your explicit approval before any message leaves the machine, even in bypassPermissions mode, and a true from any settings scope wins, so a checked-in project file can tighten but never loosen it.¹ Organizations can kill the feature entirely with deny rules on SendMessage and ListAgents plus crossSessionInbound: "refuse" in managed settings.¹

How Messages Travel

Where the other session runs determines both transport and what you can send:¹

Target	Transport	You can send
Same machine	Per-session Unix socket (named pipe on native Windows), never through Anthropic servers	New messages and replies
Your other machine	Anthropic servers, arriving over that machine’s Remote Control connection	Replies; new conversations as of v2.1.225, while Remote Control is connected5
Claude Code on the web	Anthropic servers, straight to the cloud session	Replies; new conversations to a cloud session that appears in the listing while Remote Control is connected1

When this post first ran, Anthropic’s docs page still described all cross-machine messaging as reply-only while the v2.1.225 release notes said SendMessage “can now start a conversation with your Remote Control sessions on other machines by name.” The docs have since caught up: the page now states that starting a conversation with a session on another of your machines requires v2.1.225 or later and a target that appears in the listing.¹⁵

The same-machine rule is filesystem visibility: sessions register in files on disk, so two sessions reach each other only when they see the same files. A session inside a container and one on the host cannot talk; two sessions inside the same container can.¹

Delivery respects the receiving session’s rhythm: the receiving Claude reads a message between tool calls during an active turn, never interrupting a running tool, and Claude Code starts a fresh turn with the message when the session is idle.¹ Delivered messages count toward usage like a prompt you typed.¹

Five Patterns Worth Building

1. Worktree coordination. The obvious one, and the case the documentation illustrates with its own example message: sessions working the same repository in separate worktrees tell each other what landed.¹ “Schema migration finished: the new column is tenant_id, and rebasing on main is safe now.” is the class of update that otherwise requires you to notice, switch terminals, and re-type. If several sessions share one checkout instead of worktrees, the coordination message becomes more valuable still: “I’m about to commit content/guides/, don’t stage it” prevents the classic shared-tree collision where one session commits another’s half-finished work.

2. Watcher and worker. Run a monitor session watching a deploy, a test suite, or a log, and have it message the session responsible for fixes the moment something breaks. The receiving session gets the finding as context, not as a command; it still decides, under its own permissions, what to do. Pair the watcher with background sessions and the notification hooks and you get an escalation chain that ends at a human only when it should.

3. The reporting long-runner. Kick off a migration or a long test run in one session, then have it report back to the session you actually watch.¹ Status stops living in a terminal you forgot about. The inverse also works; ask from the watching side: “Ask the session running in my other terminal whether the migration finished” is a prompt, and Claude handles discovery, addressing, and phrasing itself.¹ Since v2.1.236, skip the question: have your watching session set notify_when_idle on the long-runner and it reports back once, when it next goes idle or exits, with no polling from either side.¹¹⁰ Both sessions need v2.1.236+, and the limits follow the inbound controls. Every subscription carries a 12-hour cap: if no notice arrives by then, Claude Code drops the subscription and tells Claude to stop waiting. With refuse on the watched side, that session drops the request without recording or answering it, so the subscription expires unanswered at the cap; with refuse on the asking side, Claude Code never subscribes at all. With hold on either side the notice arrives degraded: the watched session leaves out its one-line status, and the asking session shows the notice in your transcript without delivering it to Claude.¹

4. Unattended worker fleets. Headless claude -p sessions bind inbox sockets too, so a long-running -p worker can receive messages and appears in listings.⁸ The catch: a -p session cannot show the approval dialog, so a default-held message waits out the dialogExpiry deadline (five minutes by default; dialogExpiry takes 60s, 5m, 10m, or never), then drops and reports itself expired to a sender it can reach; only a mode or settings change inside that window delivers it.¹ When the session ends with messages still held, Claude Code reports them as expired to each sender it can reach.¹ Before v2.1.225, no deadline applied at all: a held message parked without notice or expiry, and a worker that ended with held messages told their senders nothing.¹ To run a worker that takes messages unattended, start it with crossSessionInbound: "accept" in its --settings value: a per-worker grant, rather than an accept in user settings that would apply to every session you run.⁸ Bare-mode sessions skip the socket entirely and stay unreachable.⁸

5. Scripted inboxes. The quiet powerhouse: because Claude Code exports CLAUDE_CODE_MESSAGING_SOCKET to hooks and Bash commands, a script can post into a session’s own inbox.⁶ Claude Code verifies own-child messages: a hook or command posting back to its own session delivers without ceremony when no explicit crossSessionInbound applies.¹ A git hook the session’s own commit triggered, a test wrapper it launched, a deploy script it ran: any hook or Bash command the session itself started can post a line of context back into that session. Claude Code has to verify the poster as its own child; when it can verify neither by process evidence nor by token, it treats the message as one that asserts no permission class, so a bypassing session holds it for your approval instead of delivering it.¹ On native Windows the connection’s first line must be an auth line carrying CLAUDE_CODE_MESSAGING_TOKEN, or Claude Code closes the connection unread; that token is also the only way Windows verifies an own-child message.¹ On Linux the process-evidence check works even after the posting process exits; on macOS only while it still runs. After it exits on macOS, and in a container where Claude Code is PID 1, Claude Code instead verifies a child that sent the session’s exported CLAUDE_CODE_MESSAGING_TOKEN in its auth line.¹ Sandboxed commands need the socket allowed: sandbox.network.allowUnixSockets lists socket paths on macOS, and on Linux and WSL 2, where the seccomp filter cannot inspect paths, only sandbox.network.allowAllUnixSockets: true opens it; without that optional filter installed, the sandbox never blocks the socket in the first place.¹¹²

What It Refuses to Be

The limits are design decisions, and respecting them saves you from building the wrong thing.

Not an approval channel. Everything in the trust model exists to prevent one session from authorizing another’s actions. The design explicitly rules out any workflow shaped like “session A approves, session B executes.” Route authority through the human, always.¹

Not context transfer. A message is text one Claude writes to another, never conversation history or files. Anthropic’s documentation says it plainly: to move a conversation, resume the session instead.¹ Summarize; don’t dump.

Not agent teams. Independent sessions messaging each other is the peer-to-peer case. A coordinated team Claude spawns and supervises (structured protocol messages, a roster, shared task state) is the agent teams feature, and structured team messages deliberately stay inside a team.¹ If you find yourself designing a message protocol on top of cross-session text, you want agent teams.

Not a chat loop. Claude Code rate-limits repeated messages per sender, drops identical repeats arriving in a short window, and caps unread accepted messages at 50 per session, so a message loop between two sessions starves itself out by design.¹ v2.1.236 also refuses further messages up front once a rapid burst would exceed what the recipient’s inbox accepts, instead of reporting them sent while the recipient dropped them.¹⁰ Build request-and-response exchanges, not conversations.

The Traps

Privacy variables silently disable it. Cross-session messaging depends on feature-flag evaluation, and any of CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK can turn that evaluation off, taking messaging down with it, silently.³ The diagnostic is /list-agents: if the session doesn’t recognize the command, the session lacks the feature entirely; if it works but a send never arrives, something narrower applies: a deny rule, the receiver’s inbound controls, a target missing from the listing (Remote Control not connected, or the session fell past the bounded page count Claude Code reads), or a pre-v2.1.225 sender trying to start a cross-machine conversation.¹ A target that never bound an inbox is not the silent case. A session behind a privacy variable, in bare mode, or across a container boundary never appears in /list-agents, so a send to it fails loudly as a name Claude Code can’t find, and since v2.1.234 SendMessage also says when it couldn’t check your session list completely instead of treating unseen sessions as absent.¹³¹⁰ The first session after an upgrade is a late bind, not a missing one: Claude Code binds the inbox and exports the socket variable as soon as the feature-flag fetch completes, and v2.1.228 fixed that first session sometimes starting without an inbox at all.¹¹⁰ The genuinely silent cases sit on the sending side. The docs promise the hold notice and its follow-up, the arrival-time refusal notice, and the drop notice only to an interactive sender on the same machine, so a cross-machine sender or a -p worker has no promised notice for those cases. Two reports do go to “each sender it can reach”: expiry of a default-held message, and refusal when a settings change drops held messages. A message parked by an explicit hold setting never expires, so no expiry report ever comes back for it.¹

Platform and provider gaps. Native Windows arrived in v2.1.239; before that only Linux inside WSL 2 worked.¹⁹ Anthropic’s docs page puts the Windows floor at v2.1.234; the release notes first announce it in v2.1.239. Treat v2.1.239 as the safe floor.¹⁹ A session inside WSL 2 and a native Windows session on the same computer can’t reach each other either: they register under different home directories and listen on different socket types.¹ Not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry.¹

The one-way reply edge. A reply to a session on another machine, sent while the replying session is not connected to Remote Control, still arrives, but without a reply address, so the receiver cannot answer. Claude Code tells Claude as much when it sends, and v2.1.225 tightened the addressing: when Claude Code couldn’t check its own session list, it never swaps a confirmed cross-machine recipient for a same-named local session.⁵

Headless holds. The -p worker that mysteriously ignores messages is almost always a held-message problem: no dialog, no delivery. Set crossSessionInbound: "accept" on workers that should listen.⁸

Key Takeaways

For daily Claude Code users: - Run /list-agents once to see what your sessions can already reach; name important sessions with /rename so messages address cleanly. The Claude Code guide covers the session commands and settings the feature leans on. - Prompt for messages in plain language (“tell the session working on payments what we changed”) and let Claude write the message itself.¹

For automation builders: - Post into sessions from hooks and scripts via CLAUDE_CODE_MESSAGING_SOCKET; own-child messages deliver without approval friction on Linux.¹⁶ - Give unattended -p workers crossSessionInbound: "accept" in their own --settings, not globally.⁸

For teams and security reviewers: - The feature ships with the right defaults: messages carry no authority, the defaults quarantine bypassing sessions, and isolatePeerMachines plus managed-settings deny rules give you per-machine and org-wide off switches.¹ - Audit the four privacy environment variables before concluding messaging is broken. A refusing session looks identical in listings and in its own /status, so check the settings files that apply to that session rather than its status; since v2.1.238 a send from a session on the same machine also reports the refusal back.¹¹⁰

References