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

• A session beyond this machine: a cloud or Remote Control session appears in the typeahead only after Claude has listed or messaged your sessions beyond this machine, so ask Claude to list them first.
• A name with a space or other characters outside letters, digits, hyphens, and underscores: type it in double quotes, such as @"release notes". When you pick the session from the typeahead, Claude Code inserts the quotes for you.

​

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.
• Claude addresses the message to this session’s own name, as described under See which sessions Claude can reach.

• 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.
• Teammates: this session’s own agent team teammates. Before v2.1.239, teammates didn’t appear in the listing, though Claude could already message them by name.
• 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.
• 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.

• Working directories: it leaves out each local session’s working directory.
• Session names: it leaves out any session name it can’t attribute to a person, so a row left with no name reads (unnamed session).
• The first line: it leaves out the line with this session’s own name unless you typed that name at this terminal, with --name or with /rename and the name, since you launched or last resumed the session.

• 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

• Press Ctrl+O to open the transcript viewer and read the full text under the sender’s session name.
• In a session started with --verbose, Claude Code shows the full text instead of the preview.

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.
  • 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.
• Sessions on this machine: available on every provider, including Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, and Microsoft Foundry, and in sessions that run with feature-flag fetching off. On those providers, and with flag fetching off, same-machine messaging requires Claude Code v2.1.248 or later. Claude Code delivers these messages over a per-session socket on your machine, never through Anthropic servers. To stop a session from receiving them, set crossSessionInbound to refuse.
• Sessions beyond this machine: Claude finds your Claude Code on the web sessions and your sessions on other machines from a session that is connected to Remote Control, which needs a claude.ai sign-in as this session’s active authentication and the other Remote Control requirements. Claude can’t find those sessions with an API key or on Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, and Microsoft Foundry.

• /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