Anthropic has added cross-session messaging to Claude Code, allowing separate Claude Code sessions to communicate with one another. The feature is designed for developers who run multiple sessions at the same time and need them to share findings, coordinate work, or pass along updates without manually copying information between terminals.
Cross-session messaging is available starting with Claude Code v2.1.224 on macOS and Linux. Once available, it works without requiring users to enable a separate feature, although permissions and configuration settings can control which messages are delivered and whether sessions can communicate across machines.
Claude Code Adds Cross-Session Messaging
The new feature lets one Claude Code session send a plain-text message to another session. Claude can decide when another session needs information, or users can explicitly ask it to contact a different session.
This is particularly useful when several Claude Code sessions are working on different parts of the same project. For example, one session might discover a breaking change while modifying an API, while another session is working on a related component. Instead of manually switching terminals and explaining what happened, the first session can send the finding directly to the second.
Anthropic says cross-session messaging is intended for independent sessions that users start and steer themselves. It is separate from Claude Code’s existing agent teams, subagents, Remote Control, and session-resume features, which are designed for different ways of coordinating AI coding work.
What Claude Code Sessions Can Share
Messages between sessions are plain text only. A session does not send its conversation history, files, or broader context to another session.
That means the feature is better suited to passing specific findings, decisions, questions, and status updates rather than transferring an entire task. If a developer needs to move an entire conversation or its context, Anthropic recommends resuming the existing session instead.
Some of the main use cases include:
- Handing off findings: A session can tell another session about a breaking change, implementation decision, or important discovery.
- Coordinating parallel work: Multiple sessions working in separate Git worktrees can keep each other updated as changes land.
- Getting status updates: A long-running migration, test, or build can report its progress back to the session the developer is monitoring.
- Working across machines: Sessions connected through Remote Control can reply to messages from other machines or Claude Code on the web.
Claude also writes the actual message. Developers can simply tell Claude what they want another session to know rather than manually composing a message.
How Claude Code Finds Other Sessions
Claude Code uses two tools for the feature: ListAgents to discover sessions it can reach and SendMessage to send a message to a specific session.
Users can also run /list-agents or /peers to see which sessions are available. The list can include other local Claude Code sessions, depending on their configuration, as well as sessions connected through Remote Control.
Each session has a name, which can be assigned using the /rename command or the --name flag. When no name is provided, Claude Code generates one based on the working directory.
If two sessions have the same name, Claude Code includes additional information to distinguish them, including their working directories.
Messages Do Not Bypass Permissions
One important limitation is that cross-session messaging does not give one Claude session control over another.
A message from another session cannot approve a pending permission request or change configuration. It also cannot modify CLAUDE.md or other settings on behalf of the user.
Commands included in a message are treated as ordinary text. For example, if one session sends /compact, the receiving session does not automatically execute the command.
Permission prompts also remain local to each session. If a message asks the receiving Claude to perform an action that requires approval, the receiving session will still ask the user for permission.
This keeps the sessions connected while preserving the permission boundaries that apply to each individual Claude Code environment.
How Cross-Session Messaging Works Across Devices
Communication depends on where the sessions are running.
When two Claude Code sessions are on the same machine, messages are delivered through a per-session socket and do not need to pass through Anthropic’s servers.
When a session is running on another machine, communication uses Anthropic’s servers through the Remote Control connection. In that situation, cross-machine sessions are currently reply-only, meaning a session can respond to an incoming message but cannot independently start a new conversation with a remote session.
Claude Code on the web can also participate through this Remote Control connection.
There are additional restrictions for containers. A session inside a container cannot communicate with a session on the host because they use separate filesystems. Two sessions inside the same container can communicate with each other.
Developers Can Control Incoming Messages
Anthropic has also built controls for managing messages between sessions.
The crossSessionInbound setting determines what happens when a session receives a message. It can be set to:
acceptto automatically deliver incoming messages to Claude.holdto require approval before a message reaches Claude.refuseto reject incoming messages.
Developers can also require approval before messages leave their machine by enabling isolatePeerMachines. This adds another layer of control for teams that do not want AI-generated messages to automatically cross machine boundaries.
Organizations can disable cross-session messaging entirely through managed settings and permission rules.
Claude Code Cross-Session Messaging Availability
Cross-session messaging requires Claude Code v2.1.224 or later and currently works on macOS and Linux, including Linux running under WSL 2. Native Windows is not supported.
The feature is also unavailable with several providers, including Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, and Microsoft Foundry.
If the feature is available, running /list-agents or /peers can help confirm that Claude Code can discover other sessions. The /status command also displays the session’s peer address.
A More Connected Claude Code Workflow
Cross-session messaging gives Claude Code a simple way to coordinate multiple AI coding sessions without turning them into a single shared conversation. Developers can keep separate sessions focused on different tasks while allowing them to exchange the information needed to avoid duplicated work or conflicting changes.
The feature is especially relevant as developers increasingly run multiple coding agents in parallel. Rather than requiring the user to act as the messenger between terminals, Claude can now pass relevant findings and status updates between sessions while keeping permissions and configuration isolated.
(via Claude Code Docs)
