Message your other Claude Code sessions

​

When to use cross-session messaging

• Hand over a finding: when one session discovers a breaking change or makes a decision, Claude summarizes it for the session working on the affected area, instead of you re-explaining it there.
• Coordinate parallel worktrees: when sessions work the same repository in separate worktrees, Claude can tell the other sessions what landed.
• Get status from long-running work: have a migration or test run report back to the session you’re watching, or ask it yourself from there. If that session is on this machine, Claude can also ask it for one notice when it next goes idle or exits.
• Message across machines: reach one of your sessions on another machine or on the web.

• To continue one conversation in another terminal, or share its context with a new session, resume the session
• For a coordinated team of sessions Claude spawns and supervises, use agent teams
• To watch and steer many sessions from one place, use agent view
• To steer a session yourself from your phone or another device, rather than have sessions message each other, use Remote Control
• To push external events, such as CI results or chat messages, into a session, use channels

​

Message another session

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

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

Let @api-worker know the schema migration finished

​

Message delivery

• The message is over the size cap. Claude Code refuses it in the sending session, before it leaves.
• A rapid burst to a session on this machine has reached what that session’s inbox accepts. Claude Code refuses further messages to that session.
• The reply target on this machine fails a safety check, such as a symlinked target or an endpoint that isn’t the expected process. Refusing to send a cross-session message lists these checks.

• Delivered: Claude Code passes the message to the receiving Claude.
• Held: Claude Code sets the message aside undelivered. A held message reaches Claude only when you approve it or a later mode or settings change allows it.
• Refused: Claude Code drops the message without delivering it.

​

Get a notice when another session goes idle

​

Ask for a notice

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

​

What each session shows

​

Limits

• refuse on either side: nothing arrives. The watched session drops the request without recording or answering it, so the subscription expires unanswered after 12 hours, and an asking session with refuse never subscribes.
• hold on either side: the notice arrives with less. The watched session leaves the one-line status out, and the asking session shows the notice in your transcript without delivering it to Claude.

​

See which sessions Claude can reach

• Subagents: agents running inside the current session. Agent team teammates aren’t listed; Claude messages them through the team’s own roster.
• Your other local sessions: Claude Code sessions running on the same machine, including background sessions. A session appears only when it binds an inbox socket. The worker process that the supervisor process keeps ready for your next background session appears once you dispatch work to it.
• Your cloud sessions: your Claude Code on the web sessions, shown while this session is connected to Remote Control. Claude Code labels them cloud in the listing.
• Your Remote Control sessions on other machines: shown while this session is connected to Remote Control, and labeled Remote Control. Claude Code shows offline as the status of a session whose Remote Control connection has dropped.

• One session answers to the name: Claude Code delivers the message on the name alone.
• Several sessions share the name, or Claude Code couldn’t check everywhere your sessions run: Claude adds a short identifier to each row of its listing and uses the identifier in the address.

​

Message sessions on other machines

​

How a session treats an incoming message

• It can’t approve anything: a message from another session never counts as your consent, so it can’t answer a pending permission prompt on your behalf.
• It can’t change configuration: Claude Code instructs the receiving Claude never to change permission settings, CLAUDE.md, or other configuration because another session asked.
• Commands don’t run: a command in the message’s text, such as /compact, arrives as plain text. Claude Code never executes it.
• Permission prompts still fire: if acting on the message requires a permission the receiving session doesn’t have, you see the same prompt you’d see for any other work.

​

What a message looks like

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

​

Control inbound messages

• The receiving session prompts for permissions: Claude Code delivers each message. It holds one for your approval only when the sending session identifies itself as bypassing permission prompts.
• The receiving session bypasses permission prompts: Claude Code holds each message for your approval. It delivers one only when the sending session identifies itself as also bypassing.

• Approve delivers that one message to Claude.
• Deny, or dismissing the dialog, drops it.
• When the dialog stays unanswered past the dialogExpiry deadline, Claude Code closes it and drops the message. The deadline defaults to five minutes. While no terminal is attached to a background session, Claude Code leaves the dialog open past the deadline. After you attach, Claude Code closes the dialog and drops the message only if it stays unanswered for a full deadline period.
• If this session’s permission-mode class changes while messages are held, Claude Code re-applies the inbound rules, delivers the messages they now accept, and shows a notice.
• If a settings change makes refuse apply while messages are held, Claude Code drops every held message and reports a refusal to each sender it can reach.

​

Non-interactive sessions

• Before the deadline: if a mode or settings change allows the message, Claude Code delivers it.
• Past the deadline: Claude Code drops the message and reports it as expired to a sender it can reach.

​

The session’s inbox socket

• /status shows it in the Peer address row. The path is prefixed with uds:.
• Claude Code exports it to hooks and Bash commands as the CLAUDE_CODE_MESSAGING_SOCKET environment variable:
  • In a session that starts with messaging on, Claude Code exports the variable before any hook runs, including SessionStart.
  • When a session starts before Claude Code has fetched the feature flag that turns messaging on, such as the first session after you install Claude Code or upgrade from a version without messaging, Claude Code binds the inbox and exports the variable as soon as the fetch completes. Hooks and processes that started before that point keep the variable unset, while later hooks and Bash commands see it.
  • Each session exports its own socket, never one inherited from a parent session.

• macOS and Linux, including WSL 2: the line is optional. Claude Code accepts a connection with or without it.
• Native Windows: the line is required. Claude Code closes any connection whose first line isn’t a valid auth line and delivers nothing from that connection.

• Own-child messages: when no crossSessionInbound value applies, Claude Code delivers a message it verifies came from the session’s own child processes, such as a hook or Bash command posting back to its own session’s socket.
  • On Linux, including inside WSL 2, Claude Code can verify by process evidence even for a child that has already exited. On macOS it can verify that way only while the posting process is still running, and in a container where Claude Code runs as process ID 1 it has no process evidence at all. On native Windows it also has none.
  • On macOS after the posting process has exited and in containers where Claude Code runs as process ID 1, that process evidence is missing, and Claude Code instead verifies a child that sent the session’s exported CLAUDE_CODE_MESSAGING_TOKEN in the auth line that opened its connection. On native Windows, that token is the only way Claude Code verifies an own-child message.
  • When Claude Code can verify neither way, it treats the message like any other that asserts no permission class, so a session that bypasses permission prompts holds it for your approval.
• Sandboxed sessions: control whether a Bash command can reach the socket from inside the sandbox with the sandbox’s Unix-socket settings, sandbox.network.allowAllUnixSockets and sandbox.network.allowUnixSockets.

​

Restrict cross-session messaging

​

Require approval for cross-machine messages

{
  "isolatePeerMachines": true
}

​

Turn off cross-session messaging

• Stop receiving: set crossSessionInbound to refuse, and Claude Code drops inbound peer messages without delivering them. From project or local settings, refuse applies over every other source, and from your user settings it applies unless managed settings or the --settings flag set a value.
• Stop sending and listing: add permission deny rules naming SendMessage and ListAgents. Both take the bare tool name with no specifier.

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

​

Availability

• Operating system: available on macOS, Windows, and Linux, including Linux inside WSL 2.
• Provider: not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry.
• Feature-flag evaluation: when any of CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK turns off the feature-flag evaluation the feature depends on, cross-session messaging stays off. Each variable’s row says which values do that. Unset whichever applies. These variables can come from your shell, from a settings file’s env map, or from managed settings.

• /list-agents isn’t recognized: the session doesn’t have cross-session messaging. Work through the requirements above, starting with claude --version for the version requirement.
• /list-agents works but a send didn’t arrive: messaging is on, and something narrower applies:
  • Deny rules: a permission deny rule removes the SendMessage and ListAgents tools.
  • Inbound controls: the receiving session’s inbound controls can hold or drop what you send it.
  • Cloud session missing: a cloud session appears only while this session is connected to Remote Control.
  • Other-machine session missing: a session on another of your machines appears only when it runs with Remote Control and this session is connected as well.
  • Older cloud or other-machine session missing: Claude Code reads those session lists newest first and stops after a bounded number of pages, so Claude can’t message a session that fell past them by name.
  • Starting a conversation: Message sessions on other machines covers starting a conversation with a session beyond this machine.

​

Limitations

• Plain text only: Claude sends only plain text across sessions. Structured agent team protocol messages stay within a team.
• Same-machine message size is capped: Claude Code refuses a message to a session on this machine once its serialized form passes about a million characters. The refusal names the exact sizes. Nothing reaches the receiving session.
• Rapid bursts to one session are refused at the sender: once a rapid burst of messages to a session on this machine reaches what that session’s inbox accepts, Claude Code refuses further sends in the sending session. The refusal names the burst and tells Claude to batch the rest into one message or wait. Before v2.1.236, Claude Code reported those sends as sent while the receiving session dropped them.
• Message loops are throttled: in the receiving session, Claude Code rate-limits repeated messages per sender, drops identical repeats arriving within a short window, and queues at most 50 accepted messages for Claude to read. A message loop between two sessions therefore stops on its own. When the rate limit, repeat check, or queue cap drops a message from an interactive session on this machine, Claude Code tells that session which one dropped it and tells its Claude not to resend right away.

​

Related resources

• Subagents and agent teams: messaging within a single session or team
• Background agents: dispatch and monitor the parallel sessions you might message
• Remote Control: connect this session to reach your sessions on other machines
• Settings: crossSessionInbound, isolatePeerMachines, and dialogExpiry
• Permission modes: the modes behind the inbound default’s two classes
• Tools reference: the ListAgents and SendMessage rows in the tools table
• Run agents in parallel: compare the ways Claude Code runs multiple agents