Claude Code Sessions Can Now Message Each Other Directly

On August 8th, Claude released a new feature: two sessions can now communicate with each other.

If you're halfway through a task and want to open a new window, you'd normally have to reintroduce your identity and what you want to do. Now you don't need to; you can directly assign Claude Code to handle the job.

I think this feature is very useful, and I hope agents like Codex, WorkBuddy, Trae, and Qoder will push to implement it soon.

Anthropic also published an official document. I've read it, and I'll share what it says.

When to Use It

The official documentation lists four typical scenarios.

The first is handing off discovery results: when one session discovers a significant change, Claude will summarize the results for the relevant session, so you don't have to explain it again yourself.

The second is coordinating parallel worktrees: several sessions are working on the same repo in different worktrees. When one finishes and commits changes, it can directly notify the other sessions.

The third is getting the status of a long-running task: for example, if a session is running a migration or tests, it can deliver a report to the session you're currently using once it's done. You can also have your current session actively ask it if it's finished.

The fourth is cross-machine replies.

Note here: sessions on another machine or on Claude Code on the Web can currently only reply to messages that have already arrived; they cannot actively initiate a new cross-machine communication.

Using the message-passing mechanism, you can interact between independent sessions that you start and control yourself. Below are some easily confused scenarios, and Claude Code has separate features for each.

• If you want to resume the same conversation in another terminal, use resume.
• If you want Claude to create and supervise a team of collaborating members, use agent teams.
• If you want to view and guide multiple sessions in one place, use agent view.
• If you want to personally control a session from your phone or another device, use remote control.
• If you want to push CI results or chat messages into a session, use channels.

These features seem a bit similar, but they do different things.

What Exactly Does the Message Carry?

I misunderstood at first; I thought it was passing context, but it's not.

What's passed between sessions is a message, and it does not carry the complete conversation history, files, and context together.

The official documentation emphasizes this right at the beginning.

The official example of a message is:

Schema migration finished: the new column is tenant_id, and rebasing on main is safe now.

This sentence tells the other party three things: the migration has finished, the new field is called tenant_id, and you can safely rebase now.

The other session receives this notification. The message also includes the sender's name and a reply address, so the recipient knows where to send the result after processing.

As for which specific commands the migration ran, which files were changed, and why the field was ultimately named tenant_id, the other session knows none of that.

Claude Code doesn't package and compress the entire session. It just lets Claude pick out the content the other party needs to know based on the current conversation and rewrite it into a message to send.

If you want the other party to know more details, you have to explicitly tell Claude to include them in the message.

When I saw /resume mentioned in the official documentation, I had another question: is cross-session message passing related to resuming a session?

It's not.

Cross-session message sending is like passing a note between two people, while resume is like opening the original notebook.

One Tool for Finding, One for Sending

When sending messages across sessions, Claude uses two tools: ListAgents and SendMessage.

ListAgents is used to discover who it can find, and SendMessage sends the message to one of the sessions by name.

In short: one finds, one sends.

Users don't need to call these two tools themselves. Just say to Claude directly:

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

Claude will find the target and compose the actual message to send.

The official documentation also provides another prompt:

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

Both of these are prompts you give to the current Claude. What the other session ultimately receives depends on what Claude writes based on the current context.

Moreover, Claude can also send proactively.

For example, if it just made a change that affects other worktrees, or solved a problem another session was waiting for, it can proactively alert the other party upon discovery without waiting for you to prompt it.

When a message arrives at the recipient, if Claude is executing a task, it will read it between two tool calls and will not interrupt the running task.

When the recipient is idle, Claude Code will directly use this message to start a new round.

Claude will find the target itself, so you don't need to do any operations before sending a message.

If you want to see who it can currently contact, you can enter:

/list-agents

You can also use its alias:

/peers

Three types of objects will appear in the list.

• Subagents running within the current session;
• Other Claude Code sessions on the same machine, including background sessions;
• Other machines or web sessions visible after a Remote Control connection.

How Do Two Different Machines Communicate?

On the same machine, Claude Code binds an inbox socket for each session.

The session registers itself in local files. ListAgents finds other sessions through these files, and SendMessage sends the message to the other party's socket.

Messages between sessions on the same machine do not go through Anthropic's servers.

If the session is on another machine of yours, the message goes through Anthropic's servers and then reaches the specified session via that machine's remote control connection.

If it's the web version of Claude Code, it goes directly through Anthropic's servers into the cloud session.

Note: In both of the above cross-machine scenarios, you can only reply; the current session cannot actively initiate a new communication.

Claude Code does not directly scan the entire computer to see which sessions are running.

After each session starts, it registers its name and socket address in the current file system and simultaneously creates an inbox socket for receiving messages.

You can think of the registration file as an address book and the inbox socket as a mailbox.

Containers and the host machine use two independent file systems by default. Although they run on the same computer, both sides see two different address books, cannot find the address registered by the other party, and naturally cannot deliver messages to the other party's mailbox.

If both sessions run within the same container, they can see the same registration file and access each other's sockets, so they can communicate normally.

If you want messages to require confirmation before leaving the current machine, you can set:

{
  "isolatePeerMachines": true
}

Once enabled, even if the session uses bypassPermissions, cross-machine message sending will request approval. Messages sent between sessions on the same machine are not affected by this setting.

Another Session Cannot Authorize on Your Behalf

Once two Claudes can communicate with each other, permissions become an issue to consider.

Claude Code will explicitly tell the recipient that this message comes from another session, not from the user themselves.

Therefore, another session cannot approve permissions on your behalf, nor can it require the recipient to modify CLAUDE.md, permission settings, or other configurations.

If a message contains /compact, the recipient will only treat it as plain text and will not execute it directly.

The receiving end uses crosssessionInbound to decide how to handle the message after receiving it.

After receiving a message, there are three handling methods.

accept hands it directly to Claude, hold temporarily stores it, and refuse discards it outright.

If not explicitly set, Claude Code compares the permission modes of the sender and receiver.

If both sides belong to the same permission category, it is delivered normally.

If the permission categories differ, the message is first held and awaits user approval.

There's another less conspicuous point in the official documentation.

Non-interactive sessions started with claude -p will also bind an inbox socket just like regular sessions.

Using claude -p will also appear in /list-agents and can receive messages sent by other sessions.

How to Confirm You Can Use It

Cross-session messaging requires Claude Code v2.1.224 or higher.

It currently supports macOS, Linux, and WSL 2, but not native Windows.

Once the conditions are met, no manual activation is needed. Just enter /list-agents or /peers to check.

If the command is not recognized, first run:

claude --version

Then check the platform and provider.

If the command works but the message isn't delivered, you need to check the receiving end's crosssessionInbound, SendMessage permissions, and whether the other party is a remote session that can only reply.

If you want to completely disable receiving, you can set crosssessionInbound to refuse.

If you also want to disable sending and viewing the list, you can deny SendMessage and ListAgents in permissions.

{
  "permissions": {
    "deny": ["SendMessage", "ListAgents"]
  },
  "crosssessionInbound": "refuse"
}

Note here: SendMessage is also used to send messages to Subagents and Agent Teams members. If you disable it, these two types of communication will also be closed.

Additionally, cross-session messaging currently only supports plain text.

Also, Claude Code limits repeated sending; receiving the exact same message within a short time will cause it to be discarded directly. A maximum of 50 messages can be received and awaiting Claude to read.

I'll say it again: I hope agents like Codex, WorkBuddy, Trae, and Qoder will push to implement this feature soon.

Sources:

• Claude Code: "message your other Claude Code sessions".
• Claude Code: "Resume a session".