Claude Code Adds Cross‑Session Messaging: Sessions Can Now Talk to Each Other

Cross‑session messaging overview

Claude Code v2.1.224 introduced cross‑session messaging, which transfers only plain‑text messages between independently started sessions. Conversation history and files are never transmitted; the resume command must be used to move an entire context.

Two built‑in tools implement the feature: ListAgents discovers local sessions that can be contacted (invoked with /list‑agents or its alias /peers). SendMessage delivers a message to a session identified by name.

Requirements: Claude Code v2.1.224 or newer, running on macOS or Linux (including WSL2). Native Windows is not supported.

The feature differs from Agent Teams (which are managed groups of agents) and from the Agent view panel (which only monitors sessions without enabling messaging).

Full round‑trip test

With a single session, /list‑agents returns an empty list. A background worker session was started to simulate a long‑running task:

claude -p "You are a message‑test worker. Run 'sleep 15' four times in a row, then output: worker task completed. If you receive a message from another session, answer truthfully." \
  --name msg-demo-worker \
  --settings '{"crossSessionInbound":"accept"}' \
  --allowedTools "Bash(sleep:*)"

After a few seconds the main session’s agent list showed the worker. The worker’s replies were automatically inserted into the main conversation stream, prefixed with the sender’s name and a source tag. The final output included a status report, the working directory, and a note that the worker had received and answered a status query from another session, confirming that both sides retain a complete record of the exchange.

Message transport

When both sessions run on the same machine, messages travel over a local Unix socket (e.g., /tmp/cc-socks/11676.sock) with permissions srw-------, restricting access to the owning user.

Cross‑machine communication uses the Anthropic server via a Remote Control connection. In this mode only replies can be sent; a remote session cannot initiate a new message. The same limitation applies to Claude Code’s web version, which also routes messages through the Anthropic server and permits replies only.

Because discovery relies on a shared registration file on disk, sessions inside a container cannot see sessions outside the container, and sessions inside the same container are isolated from external sessions.

The socket path is exported in the environment variable CLAUDE_CODE_MESSAGING_SOCKET before any hook runs, allowing scripts and hooks to send messages into their own session.

Typical use cases

Claude’s documentation lists four common scenarios:

A session detects a breaking change and summarizes it for the affected session.

Parallel worktrees notify each other of code changes.

Long‑running migration or test sessions report status to a monitoring session.

Sessions reply to messages originating from other machines or the web version.

For moving an entire conversation, use resume. To monitor all sessions on one screen, use the Agent view panel. To control a desktop session from a phone, use Remote Control. The author finds the worktree‑parallel scenario the most practical, as it eliminates manual copy‑pasting of change summaries between sessions.