Claude Code adds cross-session messaging between agents

Claude Code has shipped cross-session messaging: a Claude session can discover the user's other running sessions with a ListAgents tool and send one of them a message with a SendMessage tool, without the user calling either tool directly. The feature requires Claude Code v2.1.224 or later and runs on macOS and Linux; when a session meets those requirements, messaging is simply on, with nothing to enable.

The documentation lists the intended uses: handing over a finding, such as a breaking change or a decision, to the session working on the affected area instead of the user re-explaining it; coordinating sessions that work the same repository in separate worktrees by telling them what landed; pulling a status update from a long-running migration or test run; and replying to a message that arrived from one of the user's sessions on another machine or on the web. Claude can decide on its own to send a message when it judges another session needs the information, or the user can prompt for one directly.

The /list-agents command shows which sessions Claude can reach: subagents inside the current session, other local Claude Code sessions on the same machine (including background sessions, as long as they bind an inbox socket), and sessions on other machines or on the web, shown while Remote Control is connected. Each session answers to a name, usually derived from its working directory folder (for example myapp-3f), settable with /rename or the --name flag; when two sessions share a name, Claude Code appends a short identifier and the working directory to tell them apart.

An arriving message is read between tool calls if the receiving Claude is mid-turn, or starts a new turn if the session is idle, and it checks against the receiving session's inbound controls before delivery: it can be delivered outright, held for the user's approval, or refused and dropped. Held-message approval dialogs expire after five minutes by default, at which point Claude Code drops the message. Which sessions hold or deliver by default depends on the crossSessionInbound setting; absent an explicit value, Claude Code decides per message from the two sessions' permission modes, treating bypass-permission sessions as one class and prompting sessions as the other.

The receiving Claude is told the text came from another session, not from the user, and the message is deliberately limited: it cannot approve a pending permission prompt on the user's behalf, it cannot change permission settings, CLAUDE.md, or other configuration because another session asked, and any command embedded in the text, such as /compact, arrives as inert plain text rather than being executed. The receiving session sees only the message text, never the sender's conversation history or files, and any action the message triggers still fires the normal permission prompts.

Containers break the reach: a session inside a container has its own filesystem and cannot see, or be seen by, a session on the host, though two sessions inside the same container can still message each other. A session started in bare mode does not bind an inbox socket, so it cannot receive messages and does not appear in the agent list; the socket itself is restricted to the user's own operating-system account, so another user's sessions on a shared machine cannot reach it. Across machines, a local Claude can only reply to a message that arrived from a remote session, never initiate contact with one, and a reply sent while not connected to Remote Control carries no reply address, so the far side cannot answer back. Setting isolatePeerMachines to true forces the user's explicit approval before any message leaves the machine at all.

Key facts

• Claude Code sessions can now discover each other with a ListAgents tool and exchange messages with a SendMessage tool, without the user calling either tool by hand.
• Requires Claude Code v2.1.224 or later; the feature runs on macOS and Linux.
• Named use cases: handing off a finding between sessions, coordinating parallel worktrees, pulling status from a long-running job, and replying to messages from sessions on other machines or the web.
• Incoming messages are delivered, held for approval, or refused; a held approval dialog expires after five minutes by default.
• Security limits on received messages: they cannot approve permission prompts or change settings/CLAUDE.md, and any command inside the text, like /compact, is never executed.

Why it matters

Running several Claude Code sessions in parallel, one per worktree, one watching a migration, one on another machine, previously meant the user manually relayed findings between terminals. Cross-session messaging lets a session pass along a discovery, a decision, or a status update directly, either because Claude judges another session needs it or because the user asks for it to be sent.

Who it affects

Anyone running multiple Claude Code sessions at once on the same machine or across machines with Remote Control connected. It requires Claude Code v2.1.224 or later and works only on macOS and Linux; the documentation does not say whether Windows support is planned.

How to use it

The /list-agents command shows every reachable session by name, drawn from its working directory folder or set with /rename or --name, with a short identifier added when names collide. From there the user can ask Claude to message a named session directly, or let Claude send one unprompted when it sees a reason. Cross-machine reach is reply-only: a local session can answer a message that arrived from a remote one but cannot start the exchange, and doing so without a Remote Control connection sends without a reply address. Two settings narrow the behavior: isolatePeerMachines requires explicit approval before any message leaves the machine, and crossSessionInbound controls whether incoming messages are delivered, held, or refused.

How solid is it

This is Claude Code's own product documentation describing a shipped feature with a specific minimum version number, not a rumor or a third-party report, so the mechanics described here are the vendor's stated behavior rather than an outside account of it.

Risks and caveats

A message from another session is explicitly barred from counting as the user's consent: it cannot answer a pending permission prompt, and Claude Code instructs the receiving session never to change permission settings, CLAUDE.md, or other configuration because another session asked. Text inside a message that looks like a command, such as /compact, is delivered as inert plain text rather than executed. A session inside a container cannot reach, or be reached by, a session on the host, since each container has its own filesystem, and a session started in bare mode never binds the inbox socket needed to receive anything. The inbox socket itself is scoped to the operating-system user, so it is not reachable by another account on a shared machine.