Message your other Claude Code sessions - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Cross-session messaging requires Claude Code v2.1.224 or later on macOS and Linux, including Linux inside WSL 2. On native Windows, it requires Claude Code v2.1.234 or later. When a session meets the requirements, messaging is on with nothing to enable.
See Availability for provider requirements and how to confirm a session has it. Cross-session messaging lets Claude deliver a message from one of your Claude Code sessions to another. When a change in one session breaks what another is building on, Claude can warn that session before you notice. When one session settles a question another is blocked on, Claude can send the answer across. A message is a piece of text one Claude writes to another, never the sender’s conversation history or files.
To move a whole conversation or its context, resume the session instead. When to use cross-session messaging Use messaging when one of your sessions has something another session needs mid-task. Claude can send a message on its own when it sees the need, for example after making a change that affects work another session is doing, or you can ask it to send one. The common cases: 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 in the cloud.
Message another session When one of your sessions learns something another session needs, such as a finding, a status, or a decision, Claude passes it along instead of you copy-pasting between terminals. Claude discovers the target with ListAgents and sends with SendMessage , so you never call either tool yourself. Claude can decide to send a message without being asked, and you can also prompt for one. To prompt one yourself, tell Claude what you want the other session to know or do.
This example is a prompt you type, not a message Claude sends: Ask the session running in my other terminal whether the migration finished Claude writes the actual message itself, so your prompt can leave the content to Claude. This prompt asks for a summary without dictating its wording, and what Claude sends varies: Explain what we just did to the session working on the payments API To name the target yourself, mention the session in your prompt: type @ followed by the first letters of the session’s name and pick the session from the typeahead, the same way you @-mention a subagent .
Requires Claude Code v2.1.232 or later. Claude Code inserts the mention, such as @api-worker , and tells Claude which session it names, so Claude can message that session without listing your sessions first. This prompt names the target with a mention: Let @api-worker know the schema migration finished The typeahead lists your other live sessions on this machine. Two cases need more than the first letters of a name: 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. You can also type the mention without the picker. When more than one live session answers to the mentioned name, Claude asks you which one you mean before sending. For what the message Claude writes looks like when it arrives, including an example of one, see what a message looks like .
Message delivery The receiving Claude reads the message between tool calls during an active turn. When the receiving session is idle, Claude Code starts a new turn with the message. A message from another session arrives as plain text. If it mentions a file or an MCP resource with @ , Claude sees the mention as written and Claude Code attaches nothing, whether the message starts a new turn or arrives during one. Claude can still open a mentioned path on the receiving machine with its own tools, subject to that session’s permissions.
Claude Code refuses a message in the following cases: 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. A session beyond this machine is listed as unable to receive cross-session messages . Claude Code refuses the message in the sending session, before it leaves this machine.
The reply target on this machine fails a safety check, such as a symlinked target. Refusing to send a cross-session message lists these checks. The receiving session checks each arriving message against its own inbound controls , and the check ends in one of three outcomes: 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. Once delivered, the message counts toward usage like a prompt you type. The receiving Claude can reply to the sender with SendMessage , except in the cases under Replies from other machines and cloud sessions and Turn off cross-session messaging . Permission boundaries stay per-session. Claude is instructed never to ask another session for an action that was denied or blocked in its own session, or that its own permission settings would block, and to route that work back to you instead.
On the receiving side, the receiving session’s own permission prompts and rules still apply to anything the message asks for. Get a notice when another session goes idle Claude can ask one of your sessions on this machine to send back one notice when that session next goes idle or exits. Idle here means the session finished a turn with nothing queued. Use it when you’re waiting on a long task in another session and want to hear when it’s done instead of checking.
Requires Claude Code v2.1.236 or later in both sessions. Ask for a notice Tell Claude what you’re waiting on. This prompt asks for a notice from the migration session: Tell me when the migration session finishes what it's working on Claude subscribes with the SendMessage tool’s notify_when_idle input, either attached to a message it’s sending anyway or on its own. On its own, Claude Code subscribes without starting a turn or spending tokens in the watched session, and sends the notice right away if that session is already idle.
Attached to a message, Claude Code delivers the message first and sends the notice later. What each session shows The watched session shows a line saying another process asked to be told when the session is next idle. The asking session shows the notice as a line naming the watched session. The line can include the time that session’s turn finished and a one-line status from that turn. If the asking session is idle, Claude Code starts a new turn with the notice.
Limits If no notice arrives within 12 hours, Claude Code drops the subscription and tells Claude, so it doesn’t keep waiting. Each side’s inbound controls apply to a
The rest of this page is on the live site.