Message your other Claude Code sessions - Claude Code Docs

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 conversation history or files. To move a whole conversation or its context, resume the session instead. Claude uses two tools for this: ListAgents to discover which agents it can reach, and SendMessage to deliver a message to one of them by name. With the same SendMessage tool, Claude can also message subagents and agent team teammates within a single session or team. This page covers messages between your independent sessions.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. Reply across machines: answer a message that arrived from one of your sessions on another machine or on the web. Across machines, Claude can only reply. It can’t start the exchange. Use messaging between independent sessions that you start and steer yourself. Claude Code has a dedicated feature for each of the other ways to run or reach multiple sessions, so use the one built for what you’re doing instead: 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 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: 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: 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, so a running tool is never interrupted. When the receiving session is idle, Claude Code starts a new turn with the message. Between two ordinary interactive sessions with default settings, Claude Code delivers the message. Delivery isn’t guaranteed in every configuration, though. 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, and the receiving Claude can reply to the sender the same way, except in the one-way cross-machine case. 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.See which sessions Claude can reach Claude finds a message’s target on its own, so you don’t need to run anything before asking it to send. To see for yourself which sessions Claude can reach, run the /list-agents command. It lists each session with the name it answers to, and that name is where Claude addresses a message. The listing covers: 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. Sessions beyond this machine: shown while Remote Control is connected and labeled Remote Control. These are your sessions on other machines and your Claude Code on the web sessions. Claude can’t send a message to start a conversation with one of these sessions. It can only reply to a message that arrived from one of them. See Message sessions on other machines. A session answers to the name you set with the /rename command or the --name flag. When you don’t set one, Claude Code names the session itself. An interactive session gets a name derived from its working directory’s folder name, such as myapp-3f. Two sessions can end up with the same name. The /list-agents output shows each local session’s working directory, which tells same-named sessions apart when they run in different directories. Claude’s own listing adds a short identifier to each row and uses it in the address when names collide.Message sessions on other machines Where the other session runs decides how a message travels and what Claude here can send:Where the other session runsHow the message travelsWhat Claude here can sendOn this machineOver a per-session socket, never through Anthropic serversNew messages and repliesOn another of your machinesThrough Anthropic servers, arriving over that machine’s Remote Control connectionReplies onlyOn Claude Code on the webThrough Anthropic servers, straight to the cloud sessionReplies only Same-machine delivery works wherever the feature is enabled. Each session registers itself in files on disk and binds its inbox socket there. When Claude lists or messages your local sessions, Claude Code reads those files to find them, so two sessions can reach each other only when they can see the same files. A container has its own filesystem, so a session inside it and a session on the host can’t reach each other. Two sessions inside the same container can still message each other, including on a self-hosted runner. A reply needs a reply address, and almost every message carries one. A reply to a session beyond this machine, sent while the replying session isn’t connected to Remote Control, still goes through as a direct request to Anthropic servers, but it arrives without a reply address, so the receiver can’t answer it. Claude is told as much when it sends. To require your approval before any message goes beyond this machine, set isolatePeerMachines.How a session treats an incoming message When session A messages session B, Claude Code tells B’s Claude that the message came from another session, not from you, and limits what the message can do: 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 When the message arrives, it appears in the conversation with its sender, queued while Claude is mid-turn or starting a new turn right away when the session is idle. Once Claude has read it, Claude Code collapses it to a one-line Message from row, which Ctrl+O expands. A message is a piece of text one Claude writes to another. Claude receives it with the sender’s name and a reply address, except for a one-way cross-machine reply, which carries no reply address. You see the name and the text, and the receiving session gets only that text, never the sender’s conversation history or files. This example is a message one Claude wrote to another, as the receiving session sees it: Control inbound messages Set crossSessionInbound to choose what a session does with messages arriving from your other sessions:ValueBehavioracceptClaude Code delivers each message to ClaudeholdClaude Code shows a notice for each message and doesn’t deliver it. If an accept later applies, per the precedence rules, Claude Code releases the held messagesrefuseClaude Code drops each message without delivering it