Claude Code Cross-Session Messaging: Your Agents Can Now Talk to Each Other

Claude Code can now send messages between your independent, running sessions. The feature landed in v2.1.224 and is documented as cross-session messaging: one session discovers your others with a ListAgents tool, delivers a short text message with a SendMessage tool, and the receiving session reads it between tool calls or starts a fresh turn if idle. No setup, no config file, no server to run. If you are on v2.1.224 or later on macOS or Linux, messaging is on with nothing to enable.

It is a small API surface with a large workflow consequence, and the design decisions around it are the interesting part.

What shipped#

Two tools do all the work, and you never call them yourself. Claude calls ListAgents to see which sessions it can reach, then SendMessage to deliver to one of them by name. The same SendMessage tool also covers subagents and agent-team teammates inside a single session, which means the deny rule that turns messaging off covers all three at once. To see what your Claude can reach, run /list-agents (alias /peers); /status shows your session's own inbox address.

What travels between sessions is deliberately narrow: plain text only. No conversation history, no files, no context. If you want another session to inherit context, the docs point you to resume instead. The receiving Claude reads a message between tool calls during an active turn, so a running tool is never interrupted, and an idle session just starts a new turn with the message.

Delivery is not guaranteed, and that is the feature's most honest detail. Each session checks inbound messages against its crossSessionInbound setting - accept, hold, or refuse - and when no setting applies, Claude Code derives the behavior from the two sessions' permission modes. A session that bypasses permission prompts holds every message from a prompting session for your approval; a prompting receiver holds messages from a bypassing sender. The approval dialog shows sender and preview, defaults to a five-minute expiry, and a session will hold at most 100 messages before dropping the oldest. Message loops cannot run forever either: repeated sends are rate-limited, identical repeats are dropped, and incoming messages cap at 50 per session.

Three more details matter for fleet operators. First, claude -p workers bind the same inbox socket as interactive sessions, so a long-running non-interactive job can receive messages, and hooks get the socket path as CLAUDE_CODE_MESSAGING_SOCKET (a hook can post back to its own session). Bare-mode sessions bind nothing. Second, across machines a session can reply but never initiate - starting the exchange requires a same-machine peer or you steering via Remote Control. Third, an isolatePeerMachines: true setting forces your approval before any message leaves the machine, even in bypass mode, and a checked-in project file can turn that requirement on but not off.

Why it matters#

Until now, coordination between independent Claude Code sessions had three channels, and all three were bad. You watched terminals yourself and copy-pasted findings. You wrote to shared files and polled. Or you used an external memory tool and hoped sessions read the same facts at the right moment. Cross-session messaging replaces the polling and the copy-paste with a first-party text channel whose defaults follow the permission system you already tuned. The docs' four use cases are the ones every parallel-agent setup hits: hand over a finding, coordinate sessions working the same repo in separate worktrees, get status from long-running work, and reply from another machine.

The permission-aware defaults are the real signal. A bypass-mode session does not get to whisper straight into another bypass-mode session - that pair holds messages for your approval. This is the same philosophy as auto mode's classifier: capability grows, safety moves into the channel itself, and organizations get a knob. Admins can refuse inbound messages and deny SendMessage/ListAgents org-wide from managed settings, and the sending side is instructed never to ask another session to do something its own session was denied. The attack surface this closes is the one we have warned about before: agent approval fatigue is what happens when every handoff pings a human, and a machine channel that respects per-session permission boundaries is the alternative to either rubber-stamping or babysitting.

It also completes a ladder Anthropic has been building for months. Subagents run inside one session. Agent teams are sessions Claude spawns and supervises. Cross-session messaging is the layer above: sessions you started independently, coordinating without you as the relay. The docs are careful about the boundaries between them - resume for context, teams for supervised work, agent view for watching many sessions, Remote Control for steering from your phone, channels for pushing CI events in. That routing discipline is the framework teams should copy when they plan their own multi-session setups: one tool per shape, and messaging only where sessions are peers.

Where it stops#

The boundaries are as informative as the feature. Native Windows is out. Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry are out, which means cross-session messaging joins the list of Claude Code features that skip the hosted-model routes. Plain text only, so no structured team protocol across sessions. And the docs are explicit that messaging is for sessions you start and steer yourself - the mechanism is not a supervisor, and it does not replace the worktree discipline that keeps parallel sessions from colliding on the same checkout. The message is the coordination signal; the filesystem still does the coordination.

The practical play for a fleet right now: run long tasks in claude -p workers with crossSessionInbound set to accept, let your interactive session ask them for status, and let worktree peers warn each other the moment a landed change breaks a shared contract. That pattern is testable today with no new tooling, and it makes the terminal a room where the agents can talk, instead of a row of screens you switch between.

Continue Reading#

• Git Worktrees + Claude Code: The Parallel Agent Guide - how to structure the repos that make parallel sessions safe, before the messaging channel is useful
• Claude Code Subagents vs Agent Teams vs Workflows - where cross-session messaging sits relative to the other multi-agent shapes
• Claude Code Auto Mode Explained - the permission system that decides when a cross-session message needs your approval
• Agent Approval Fatigue Is a Security Bug - why the held-message dialog design matters for how people actually run agents
• What Is Claude Code - the full picture of the tool this feature extends

Sources#

• Claude Code docs: Cross-session messaging
• anthropics/claude-code: v2.1.224 release
• Claude Code docs: Settings reference (crossSessionInbound)