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 the moment it starts (mine sits at /tmp/cc-socks/38590.sock, with owner-only permissions), and any other session you run can drop a text message into it.¹ 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 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, with v2.1.225 adding 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 each quietly disable the feature.³

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) lists every session Claude can reach: subagents inside the current session, 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 is exported to every hook and Bash command, holding the session’s own socket path.⁶ More on why that matters below.

Verifying on my own machine: a session running v2.1.226 lists two peer sessions with their state (“busy”) and age, and the socket file carries srw------- permissions: 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 myapp-3f.¹ When two sessions collide on a name, the listing distinguishes them by working directory and a short identifier.¹

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. The receiving Claude is instructed 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 four 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. 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.¹ 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:¹

One docs conflict worth flagging: as of this writing, Anthropic’s cross-session messaging page still describes all cross-machine messaging as reply-only, while the v2.1.225 release notes say SendMessage “can now start a conversation with your Remote Control sessions on other machines by name.” The release notes are newer; the docs page lags the release.¹⁵

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: a message is read between tool calls during an active turn, never interrupting a running tool, and starts a fresh turn 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 documentation’s own example message, 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 this 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 in my other terminal whether the migration finished” is a prompt, and Claude handles discovery, addressing, and phrasing itself.¹

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 held message stays held with no path to delivery short of a settings or mode change (v2.1.225 also fixed such messages parking without notice or expiry). 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_MESSAGING_SOCKET is exported 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 nightly job, a git hook, a CI wrapper: anything that can write to a Unix socket can now inject a line of context into the session that spawned it. On Linux the verification works even after the posting process exits; on macOS only while it still runs; in a container where Claude Code is PID 1, verification fails and the message falls back to normal inbound rules.¹ Sandboxed commands need the socket allowed via sandbox.network.allowUnixSockets.¹

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. Any workflow shaped like “session A approves, session B executes” is explicitly designed against. 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.¹ 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 command is not even recognized, 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, or a cross-machine target that only accepts replies.¹

Platform and provider gaps. No native Windows (Linux inside WSL 2 works). 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 is told as much when it sends, and v2.1.225’s fixes tightened the addressing so a confirmed cross-machine recipient is never silently swapped 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. - 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, bypassing sessions are quarantined by default, 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, and know that a refusing session shows no visible difference to its peers.¹

References