New

Cross-session messaging: your Claude Code sessions can finally talk to each other

Since August 2026, one Claude Code session can message another with ListAgents and SendMessage. How it works, security, settings and concrete use cases.

  • Tutorial
  • Productivity
Published

Quick answer

If you run several Claude Code sessions in parallel, you know the drill: one session renames a database column, and you're the one who goes to warn the other, copy-pasting between terminals. Since v2.1.224, released the week of August 3 to 7, 2026, you don't have to. Your sessions can message each other.

It's like going from an office where everyone works with headphones on to an office with an internal chat. Everyone keeps their own desk and files, but you can pass on information without getting up.

How it works

Claude uses two tools: ListAgents to find your other sessions, and SendMessage to write to them. You never call these tools yourself. You ask in plain language, or Claude decides on its own to send a message when a change it just made affects another session.

An important point: a message is text Claude writes for the other session. It's never your conversation history or your files. To move a whole conversation, resume the session instead.

Example from the official docs, with two sessions open on the same machine:

Tell the session working on the payments API that users.name is now users.display_name

The receiving session shows a dim line like › Message from @api-worker: Schema migration finished (ctrl+o to expand). Ctrl+O opens the full text. Claude always reads the full message, whether or not you expand it.

Target a specific session

Since v2.1.232, you can name the target session with @, just like mentioning a subagent. Type @ then the first letters of its name and pick it from the list. 

Let @api-worker know the schema migration finished

To give a session a clear name, use /rename or the --name flag at launch. Without a name, Claude Code generates one.

See who's reachable

The /list-agents command (alias /peers) shows the sessions Claude can reach: the current session's subagents, agent team teammates, your other local sessions, and your cloud or other-machine sessions if you're connected to Remote Control.

Concrete use cases

The docs list four typical situations:

1

Hand over a finding

A 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.

2

Coordinate parallel worktrees

Several sessions work on the same repo in separate worktrees. Claude tells the others what just landed.

3

Track long-running work

A migration or test run in another session can report back to the one you're watching.

4

Reach another machine

Through Remote Control, you can message a session on another of your machines or in the cloud.

Get notified when a session is done

Since v2.1.236, Claude can ask another local session to send back a single notice when it next goes idle or exits. Handy when you're waiting on a migration:

Tell me when the migration session finishes what it's working on

If no notice arrives within 12 hours, the subscription expires and Claude is told, so it doesn't wait forever.

The awkward question: security

Letting agents talk to each other can be worrying. The docs set clear rules on what an incoming message can do:

  • It can't approve anything. A message from another session never counts as your consent and can't answer a permission prompt on your behalf.
  • It can't change configuration. Claude is instructed never to change permissions, CLAUDE.md or other settings because another session asked.
  • Commands don't run. A /compact written in a message arrives as plain text.
  • Permission prompts still fire. If acting on the message requires a permission the session doesn't have, you see the usual prompt.

In auto mode, the classifier also reviews every message a session sends to another before delivering it.

On the same machine, messages travel over a per-session socket (a named pipe on Windows), never through Anthropic's servers. To another machine or the cloud, they go through Anthropic's servers via Remote Control.

Useful settings

The crossSessionInbound setting decides what happens to incoming messages:

ValueEffect
acceptEvery message is delivered to Claude
holdA notice is shown, the message isn't delivered
refuseThe message is dropped without delivery

To require your approval before any message leaves the machine, turn on isolatePeerMachines. And to turn the feature off entirely for an organization, the docs suggest this in managed settings:

{
"permissions": {
  "deny": ["SendMessage", "ListAgents"]
},
"crossSessionInbound": "refuse"
}

Careful: denying SendMessage also cuts messaging to subagents and agent team teammates, since it's the same tool.

Availability and limits

  • Versions: v2.1.224 minimum on macOS, Linux and WSL 2, v2.1.234 minimum on native Windows.
  • Isolation: a session in a container and a session on the host can't reach each other. Neither can a WSL 2 session and a native Windows session on the same computer.
  • Text only: no attachments. A local message is refused beyond about a million characters.
  • Loops: the receiving session throttles repeated messages and queues at most 50 accepted messages, so a loop between two sessions stops on its own.

If /list-agents isn't recognized, your session doesn't have the feature: start with claude --version.

Next steps