Claude Code Cross-Session Messaging Lets One Session Warn Another the Moment Something Breaks

Claude Code cross-session messaging lets one of your Claude Code sessions send a message directly to another, without you relaying the update by hand between terminal windows. It shipped as a documented, first-party feature in Claude Code v2.1.224, and it solves a specific, common annoyance: running two or three sessions on the same repo or the same machine, and being the only channel between them.

What it actually does

The mechanism is two tools that Claude calls on its own, never something you invoke directly. ListAgents finds the other sessions Claude can reach. SendMessage delivers text to one of them by name. Run /list-agents (or its shorter alias, /peers) yourself at any point to see the same list Claude sees: other sessions on your machine, sessions inside claude -p background workers, cloud sessions from Claude Code on the web, and sessions on other machines, all labeled by name.

A message is plain text only. Not conversation history, not files, not permissions. If you want a session to pick up where another left off with full context, that's a job for resuming a session, not for cross-session messaging. This feature exists for the narrower case: session A learns something session B needs mid-task, and Claude hands it across instead of you doing the copy-paste.

Anthropic's own framing of the use case is direct: 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 session is blocked on, Claude can send the answer across. You can ask for this explicitly ("tell the session in my other terminal the migration finished") or let Claude decide to send one on its own when it spots the need.

Where messages actually travel

This is the part worth being precise about, since it changes depending on where the other session runs:

• Same machine: the message travels over a per-session socket, and never touches Anthropic's servers.
• Another machine you own: the message goes through Anthropic servers, arriving on the target machine over its Remote Control connection.
• Claude Code on the web: also routed through Anthropic servers, straight into the cloud session.

Cross-machine delivery depends on Remote Control being active on the receiving side. Starting a new conversation with a session on another machine (rather than just replying to one) needs Claude Code v2.1.225 or later. A message sent to a session beyond your own machine while your own session isn't connected to Remote Control still goes through, but arrives with no reply address, so the other side can't answer back.

Each session finds its local peers by registering itself in files on disk and binding an inbox socket there. Two sessions can only see each other if they can see the same filesystem, which is why a session inside a container and a session on the host can't reach each other, while two sessions inside the same container can.

Setup, versions, and the platform gap

There is genuinely nothing to turn on. If your session is on Claude Code v2.1.224 or later, on macOS or Linux, on a supported provider, messaging is live by default. Run /list-agents; if the command isn't recognized, you're either on an older version or missing one of the requirements below.

The honest limitation: this doesn't run on native Windows. It does work inside WSL 2 on Windows, since that's Linux underneath, but there's no native Windows path as of this writing. It's also unavailable on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry, and it silently stays off if DISABLE_TELEMETRY, DO_NOT_TRACK, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, or DISABLE_GROWTHBOOK is set anywhere in your environment or settings, because the feature depends on the same flag evaluation those variables turn off.

The safety rails worth knowing before you rely on it

A message from another session is never treated as your consent. Claude Code tells the receiving session the message came from a peer, not from you, and that session can't use it to approve a pending permission prompt, change CLAUDE.md or permission settings, or execute a command embedded in the text. If the receiving session needs a permission it doesn't have to act on what arrived, you still see the normal prompt.

Inbound handling is also configurable per session through the crossSessionInbound setting: accept delivers everything, hold queues messages for your approval, refuse drops them outright. Left unset, Claude Code applies a sensible default on its own: a session that already prompts you for permissions accepts incoming messages freely, while a session running in a bypass-permissions mode holds incoming messages for your approval unless the sender is also in a bypass mode. If you want to require your own sign-off before anything leaves your machine at all, isolatePeerMachines: true forces that gate regardless of permission mode.

Why this is worth adopting now

The obvious fit is parallel git worktrees or a build-and-test split, where you're running one session refactoring an API and another building the client against it. Instead of tabbing over to paste "the endpoint signature changed" into the second terminal, the first session can just send it. The same applies to a long migration or test run in a background session: it can report back to the session you're actually watching instead of you polling it.

It's a small mechanic, but it removes a specific kind of manual labor that scales badly, the more sessions you run in parallel, the more relaying you're doing by hand, and cross-session messaging is the first-party answer to that specifically, rather than something bolted on through a third-party MCP server or a chat bridge.

What's still missing

There's no built-in way to broadcast one message to every session at once. Delivery is one-to-one, addressed by session name, and if two sessions share a name (a common case if you have two worktrees both auto-named from a folder), Claude Code disambiguates with a short identifier rather than the name alone. Message loops between two sessions are throttled and capped, which is a reasonable guard, but worth knowing if you're building any kind of automated back-and-forth on top of this rather than using it for one-off handoffs.

The Hacker News discussion around the feature's release drew 153 points, a solid but not explosive reaction, consistent with a utility feature aimed squarely at people already running multiple Claude Code sessions rather than a headline capability.

As of today, this is documented at Anthropic's official Claude Code docs under "Message your other Claude Code sessions," and the version and platform details above reflect that page directly.