Cross-Session Messaging

1. What Is Cross-Session Messaging?

Imagine you have two Claude Code sessions running at the same time:

Session A discovers that an API schema has changed. Without messaging, you may have to copy the information yourself into Session B. With cross-session messaging, Claude can send the relevant text directly to the other session.

2. Why Is It Useful?

• Hand off findings: one session can tell another about a breaking change or important decision.
• Coordinate parallel worktrees: sessions working in separate worktrees can tell each other what has landed.
• Get long-running status: a migration or test session can report when its work is finished.
• Work across machines: with the appropriate Remote Control setup, a session can reach another machine or Claude Code on the web.

3. When Should You Use It?

4. Requirements and Availability

The current documentation states that cross-session messaging requires Claude Code v2.1.224+ on macOS, Linux, and WSL 2, and v2.1.234+ on native Windows. Messaging is enabled automatically when the session meets the requirements.

For same-machine messaging on certain providers or when feature-flag fetching is disabled, the current docs require v2.1.248+.

5. How Claude Sends a Message

You normally do not call the messaging tools yourself. Claude uses two tools:

You can simply ask Claude for the communication you want:

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

Or describe what another session needs to know:

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

6. Targeting a Specific Session

In supported versions, you can name another live session with an @ mention. For example:

Let @api-worker know the schema migration finished

The typeahead can help select the target. If a session name contains spaces or other special characters, Claude Code can use a quoted mention such as @"release notes".

7. What Happens When a Message Arrives?

A running receiving session reads the message between tool calls, so an active tool is not interrupted. If the receiving session is idle, Claude Code starts a new turn with the message.

The receiving Claude gets the message text, the sender's name, and normally a reply address. It does not receive the sender's conversation history or files.

8. Message Safety and Permissions

Messages from another Claude session do not count as your consent.

• A message cannot approve a pending permission request for you.
• A message cannot instruct Claude to change permission settings, CLAUDE.md, or other configuration on the basis of another session's request.
• Commands written inside the message are plain text; they are not automatically executed.
• If the requested action needs permission, the receiving session's normal permission rules still apply.

9. Incoming Message Controls

The setting crossSessionInbound controls how a session treats messages arriving from other sessions.

You can also access the setting from the /config interface in supported versions, where the row is named Messages from your other sessions.

10. Default Permission Behavior

When you have not explicitly configured crossSessionInbound, Claude Code determines behavior based on the permission modes of the sender and receiver.

• If the receiving session normally prompts for permissions, messages are generally delivered, with certain cases held for approval.
• If the receiving session bypasses permission prompts, incoming messages can be held for your approval.

When a message is held, the approval dialog can show the sender and a preview. You can approve or deny that individual message.

11. Waiting for Another Session to Finish

Claude can request a one-time notice when another local session next becomes idle or exits.

Tell me when the migration session finishes what it's working on

This uses notify_when_idle. It is useful for long-running migrations, tests, or other work where repeatedly checking the other terminal is inconvenient.

12. Listing Reachable Sessions

Run:

/list-agents

You can also use:

/peers

The list can include:

• Subagents in the current session
• Agent-team teammates
• Other local Claude Code sessions
• Cloud sessions when connected through Remote Control
• Remote Control sessions on other machines

13. Messaging Across Machines

The transport depends on where the target session runs:

14. Protecting Cross-Machine Messages

If you want explicit approval before messages leave the current machine, set:

{
  "isolatePeerMachines": true
}

This requires approval before SendMessage reaches a session beyond the current machine, including when bypass permissions would otherwise skip ordinary prompts.

15. Turning Messaging Off

You can control receiving separately from sending/listing.

Stop receiving

{
  "crossSessionInbound": "refuse"
}

Stop sending and listing

Add permission deny rules for:

SendMessage
ListAgents

Organization-wide example

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

16. The Inbox Socket

Each session with cross-session messaging enabled can bind an inbox endpoint used by other local sessions.

• macOS/Linux/WSL 2: Unix domain socket
• Native Windows: named pipe
• /status shows the Peer address
• Hooks and Bash can receive CLAUDE_CODE_MESSAGING_SOCKET
• A per-session CLAUDE_CODE_MESSAGING_TOKEN is also exported

This section mainly matters when a session you expect is missing from the agent list, or when a script/hook needs to post into a session.

17. Non-Interactive Sessions

A long-running claude -p session can bind an inbox and receive messages. Bare mode does not bind the socket, so a bare-mode session cannot receive cross-session messages and does not appear in the agent list.

A -p session cannot display an interactive approval dialog. If unattended message handling is needed, the documentation describes configuring crossSessionInbound explicitly, for example with accept.

18. Common Troubleshooting

19. Limitations

• Messages between sessions are plain text.
• Same-machine messages have a serialized size cap of about one million characters.
• Rapid bursts to one session can be refused.
• Repeated message loops are throttled and duplicate bursts can be dropped.
• The receiving side can queue at most 50 accepted messages for Claude to read.

20. Real-World Example

21. Cross-Session Messaging vs Agent Teams

22. Beginner Checklist

1. Make sure your Claude Code version supports cross-session messaging.
2. Run /list-agents to see reachable sessions.
3. Ask Claude to send a concise finding or status update.
4. Use @session-name when you want to target a specific session.
5. Remember that messages do not carry conversation history or files.
6. Check crossSessionInbound when messages are held or refused.
7. Use isolatePeerMachines if you want approval before messages leave the machine.
8. Use Agent Teams instead when you need a coordinated team rather than simple peer communication.

23. Quick Memory Map

24. Interview / Revision Questions

1. What problem does cross-session messaging solve?
2. Does a message transfer the sender's conversation history?
3. What are ListAgents and SendMessage?
4. How can you see sessions Claude can reach?
5. What is the difference between accept, hold, and refuse?
6. How does a message differ from a permission granted by the user?
7. What does isolatePeerMachines protect?
8. How is cross-session messaging different from Agent Teams?
9. Why might a -p session be useful for messaging?
10. What are the major message-size and queue limitations?

25. Practice Exercises

26. Final Takeaway

Cross-session messaging is Claude Code's communication layer for independent sessions. It lets one session pass a finding, decision, or status update to another without merging their contexts.