Claude Code Cross-Session Messaging: How It Works, When to Use It, and Security Considerations

TL;DR

Claude Code can automatically send a plain‑text message from one of your active sessions to another, allowing sessions to warn each other about breaking changes, share status updates, or answer blocked questions without manual copy‑pasting. The feature respects per‑session inbound controls, permission modes, and can be restricted or disabled entirely.

---

What Cross‑Session Messaging Is

Cross‑session messaging is a built‑in Claude Code capability that lets a Claude instance deliver a text message to another Claude session you own. It does not transfer conversation history, files, or structured data—only the message text.

• Tools used internally: ListAgents (discover reachable agents) and SendMessage (deliver the message). Users never invoke these tools directly.
• Scope: Works between independent sessions on the same machine, across machines via Remote Control, or to web‑based Claude Code sessions. It cannot start a new conversation on a remote session; it can only reply to an incoming message.

---

When to Use It

Use messaging when a session learns something that another session needs mid‑task. Typical patterns include:

Use case	How messaging helps
Hand over a finding	One session discovers a breaking change; Claude summarizes and sends it to the dependent session, avoiding manual re‑explanation.
Coordinate parallel worktrees	Multiple sessions operate on different worktrees of the same repo; Claude notifies each other of landed changes.
Get status from long‑running work	A migration or test run can report progress back to a monitoring session.
Reply across machines	A session on a laptop can answer a message that arrived from a desktop session.

If you need to resume a session, run a coordinated agent team, watch many sessions, control a session remotely, or push external events, Claude Code already provides dedicated features (resume, agent teams, agent view, Remote Control, channels). Use cross‑session messaging only for the scenarios above.

---

How a Message Is Sent and Delivered

1. Discovery – Claude calls ListAgents to find reachable sessions.
2. Sending – Claude calls SendMessage with the target’s name and the message text.
3. Delivery – The receiving session processes the message during its current turn or starts a new turn if idle.
4. Outcome – The inbound controls decide whether the message is Delivered, Held, or Refused.

Delivered messages are passed to the receiving Claude and count toward usage like a normal prompt. Held messages sit in a queue until you approve them (or settings change). Refused messages are dropped silently.

---

Inbound Controls (crossSessionInbound)

The setting crossSessionInbound determines the default handling of incoming messages:

Value	Behaviour
accept	All messages are delivered.
hold	Each message triggers a notice; you must approve it before delivery.
refuse	Messages are dropped without delivery.

When no explicit value applies, Claude falls back to permission‑mode classes:

• Sessions that bypass permission prompts (e.g., auto, acceptEdits) cause incoming messages to be held unless the sender also bypasses.
• Sessions that prompt for permissions deliver messages immediately.

If a held message is approved, it is delivered; if it expires (default 5 minutes) or you deny it, it is dropped. A session can hold up to 100 messages; older ones are discarded.

---

Cross‑Machine Messaging Limits

Destination	Transport	What can be sent
Same machine	Direct Unix‑domain socket	New messages and replies
Another of your machines (Remote Control)	Anthropic servers → Remote Control	Replies only
Claude Code on the web	Anthropic servers	Replies only

Messages to remote machines are reply‑only; a session cannot initiate a new exchange with a remote peer. To require explicit approval before any cross‑machine message leaves the host, set isolatePeerMachines=true.

---

Security and Permission Model

• No implicit consent – An incoming message never counts as user approval. It cannot approve permission prompts, change configuration files, or execute commands embedded in the text.
• Permission prompts still fire – If acting on the message requires a permission the receiving session lacks, you see the same prompt as for any other operation.
• Tool denial – Administrators can block messaging entirely by denying the SendMessage and ListAgents tools in permission rules.
• Potential attack surface – As noted by a Hacker News commenter, exposing a messaging channel adds a vector for remote code execution if mis‑configured. Proper inbound controls (crossSessionInbound=hold or refuse) and isolatePeerMachines mitigate this risk.

---

Managing Sessions and Names

• Use /list-agents (or /peers) to see reachable sessions and their names.
• Sessions are addressed by the name set with /rename or the --name CLI flag. If names collide, Claude adds a short identifier to disambiguate.
• Only sessions that have bound an inbox socket appear in the list. A headless claude -p session in bare mode does not bind a socket and therefore cannot receive messages.
• The inbox socket path is exposed via CLAUDE_CODE_MESSAGING_SOCKET and shown in /status under Peer address.

---

Practical Tips from the Community

"I built this myself with tmux, a memory tree, and handoff files. It minimized duplicate context and saved token costs." – eigenblake

"I’ve scripted Claude to message other models across my fleet of Linux machines via Tailscale. It works well but sometimes needs manual intervention to stop loops." – Cyuonut

"I used the feature and saw messages like ‘hold swarm, I prepare safe exfil’. The system throttles repeated messages and caps pending messages at 50 per session, preventing runaway loops." – dist‑epoch

These anecdotes confirm that the built‑in tool is comparable to custom orchestrations (tmux, IRC, HTTP hooks) while offering tighter integration with Claude’s permission system.

---

How to Turn Messaging Off

• Stop receiving – Set crossSessionInbound=refuse in user, project, or managed settings.
• Stop sending/listing – Add permission deny rules for SendMessage and ListAgents.
• Organization‑wide disable – Managed settings can combine both approaches, ensuring no session can send or receive messages.

Even when disabled, each session still binds its inbox socket; messages are simply dropped without visible side effects.

---

Availability and Requirements

• Version – Requires Claude Code v2.1.224 or later.
• OS – Supported on macOS and Linux (including WSL 2). Not available on native Windows.
• Providers – Not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, or Microsoft Foundry.
• Feature flags – The feature is disabled if any of the environment variables CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK are set to values that turn off the underlying flag.

Check a session with /list-agents (or /peers). If the command is unrecognized, the session lacks the required version or feature flag.

---

Limitations

• Only plain‑text messages are supported; structured team protocols stay within agent teams.
• Message loops are throttled: identical repeats within a short window are dropped, and a session caps pending messages at 50.
• Containers have isolated filesystems; sessions inside a container cannot reach host sessions unless they share the same socket directory.

---

Bottom Line

Claude Code’s cross‑session messaging provides a lightweight, permission‑aware way for independent Claude sessions to coordinate work, share findings, and report status without manual copy‑pasting. By configuring inbound controls, isolation flags, and permission rules, users can balance convenience with security.