Preface¶

If you run Claude Code in multiple terminals at the same time, you have almost certainly encountered this scenario: Window A just finished a database migration, Window B is still writing an interface that depends on the new table structure, and Window C is modifying the frontend in another worktree — they have no way of knowing each other’s progress, so you have to manually copy terminal output to another window and ask Claude to recontextualize the information all over again.

On August 7, 2026, Anthropic launched the Cross-Session Messaging feature in Claude Code v2.1.224. Sessions running independently on macOS and Linux can discover each other via ListAgents and send plain text summaries to each other via SendMessage, eliminating the need to copy information between terminals back and forth. This update has been covered in official documentation and media outlets such as MacRumors.

This article verifies the feature details based on Anthropic’s official documentation, and introduces its working principle, applicable scenarios, usage methods, and security boundaries.

What is Cross-Session Messaging¶

Cross-session messaging refers to the process where Claude relays a text message between multiple Claude Code sessions that you have started yourself.

A few key points need to be clarified:
1. Only summaries are transmitted, not full context. The message is plain text sent from one Claude instance to another, and does not include conversation history, file contents, or permission status. If you want to continue an entire conversation, you should use the session resume feature instead of cross-session messaging.
2. You do not need to manually call the tools. ListAgents and SendMessage are tools that Claude uses in the background. You can simply tell Claude “notify another session about this matter” using natural language in the terminal.
3. Enabled by default, no extra configuration required. As long as the version, platform, and provider meet the requirements, the feature will be available automatically.

The demo Anthropic posted on X also emphasized this: Claude sends a summary, and the receiving instance picks up the message in the middle of its current task to continue working.

Core Mechanisms: ListAgents and SendMessage¶

Claude Code has introduced two tools for cross-session communication:

The same SendMessage tool also serves sub-agents within a single session and Agent Teams teammates, but cross-session messaging targets sessions you start independently and steer yourself, which is a different level of collaboration than Agent Teams (teams generated and coordinated by Claude).

How to view reachable sessions¶

Enter the following command in any session:

/list-agents

The alias is /peers. The output will list the name, working directory, and other information for each session. The session name can be customized via /rename or the --name parameter at startup; if not set, Claude Code will automatically generate one based on the working directory folder name, for example myapp-3f.

If the /list-agents command is not recognized, it means the current session does not support cross-session messaging. You should first check if claude --version is at least v2.1.224.

How messages are delivered¶

The receiving Claude instance reads messages between tool calls, and will not interrupt an ongoing tool execution. If the receiving session is idle, Claude Code will start a new conversation to process the message.

After the message arrives, a card with the sender’s identifier will be displayed in the session; once read, it will collapse to a line reading Message from, and you can press Ctrl+O to expand and view the original text.

Typical Use Cases¶

The official documentation lists the following common use cases:
1. Share discoveries and decisions: When one session discovers a breaking change or makes an architectural decision, Claude automatically sends a summary to another session working on the relevant modules.
2. Parallel worktree collaboration: Multiple sessions develop in different git worktrees in parallel. After one party merges or commits changes, they can notify other sessions “a certain change has been landed on main, you can rebase now”.
3. Long task status reports: Time-consuming tasks such as migrations or test suites run in background sessions, and report results to the main session upon completion. You can also actively ask “has the migration in the other terminal finished running yet”.
4. Cross-device replies: After a session connected via Remote Control from a phone or web client sends a message, the local terminal can reply (cross-machine scenarios only support replying, not initiating messages first).

Claude can either proactively send messages when it identifies a need for coordination, or send them at your prompt. For example:

Ask the session running in my other terminal whether the migration finished

Or:

Explain what we just did to the session working on the payments API

Claude will organize the message wording on its own, and you do not need to specify the content word for word.

Message Transmission Paths and Security Boundaries¶

Local vs. Cross-Machine¶

Messages on the same machine use local sockets, and both MacRumors and the official documentation confirm that this traffic is not uploaded to Anthropic. Cross-machine scenarios must go through the server, and only support replying to messages sent first by the other party.

If you want additional oversight over cross-machine messages, you can enable isolatePeerMachines: true in the settings, which will require your explicit approval before each outgoing message is sent.

Permission Restrictions for Receiving Parties¶

Messages from other sessions cannot replace your operational authorization, with the following specific restrictions:
- Cannot approve permissions on your behalf: The message does not count as your consent, and cannot bypass pending permission prompts.
- Cannot modify configurations: The receiving Claude instance is explicitly prohibited from changing permission settings, CLAUDE.md, and other configurations due to requests from another session.
- Commands will not be executed: Text such as /compact in messages is treated as plain text, and Claude Code will not execute them.
- Sensitive operations still require your confirmation: If the work triggered by a message requires permissions, the receiving session will still pop up the same prompt as if you had operated manually.

Additionally, you can control inbound messages via the crossSessionInbound setting: accept (deliver directly), hold (store temporarily for approval), or refuse (discard directly). The default policy also categorizes messages based on both parties’ permission modes — for example, if the receiving session is in bypass mode, messages from sessions in normal mode will be held waiting for your approval.

Platform Support and Limitations¶

Version requirement: Claude Code v2.1.224 or higher.
Operating systems: macOS, Linux (including WSL 2). Native Windows is not supported yet.
Unsupported providers: Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, Microsoft Foundry.
Features that may disable the function: If any of the following environment variables are set which disable feature flag evaluation: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK, cross-session messaging will also be unavailable.

Other limitations:
- Only plain text is supported, no structured Agent Teams protocol messages.
- Loop prevention: Rate limits are in place for duplicate messages, and repeated deliveries of the same content within a short period will be discarded; each session can queue up to 50 pending messages at most.
- Containers and their hosts usually cannot send messages to each other due to filesystem isolation; sessions within the same container can.
- Headless sessions started with claude -p can also receive messages (except in bare mode).

This same version also includes approximately 31 other changes, such as the claude self-hosted-runner command for Team and Enterprise plans, and a sandbox security fix for Linux/macOS (the issue where denyRead/denyWrite rules with trailing slashes were silently ignored).

Differences Between Cross-Session Messaging, Agent Teams, and Subagents¶

Claude Code has multiple “multi-agent” modes that are easy to confuse. Here is a brief comparison:

Cross-session messaging solves the problem of “I have multiple windows open, how can I get them to share information”; Agent Teams solves the problem of “let Claude form its own team to do work”. The two can coexist, but their positioning is different.

How to Disable or Restrict the Feature¶

If you do not need this function, you can disable it in different directions:
Stop receiving messages: Set crossSessionInbound to refuse.
Stop sending messages and discovering peers: Deny SendMessage and ListAgents in permission rules (note: this will also disable messaging capabilities for sub-agents and Agent Teams teammates).
Organization administrators can also uniformly disable this feature in managed settings.

Summary¶

Cross-session messaging in Claude Code v2.1.224 turns the manual task of “telling Window B what Window A discovered” into automatic summary delivery between Claude instances. ListAgents is responsible for discovery, and SendMessage is responsible for delivery; same-machine traffic uses local sockets, while cross-machine traffic goes through Remote Control and only supports replying.

It does not transfer files or conversation history, and cannot approve sensitive operations on your behalf — the security boundaries are still firmly in your control. For developers who work across multiple worktrees or terminals in parallel, this is a practical small upgrade: fewer window switches, fewer log copy-pastes, and a smoother collaboration rhythm.

After upgrading, you can confirm your version by running claude --version in the terminal, then enter /list-agents to see which sessions are currently online. If you are running multiple Claude Code instances on macOS or Linux, you can have one session send a message to another to test it out.