Claude Code sessions messaging each other: cross-session messaging

You're running two Claude Code sessions: one changing the database schema, one writing an API on top of it. The first just renamed a column, and the second is about to write code against the old name. Previously you'd copy-paste between terminals. With cross-session messaging, Claude in one session can message the other directly, even on its own initiative when it sees the need.

How to use it

Nothing to enable: eligible sessions (Claude Code v2.1.224+ on macOS/Linux, v2.1.234+ on Windows) have it. Just tell Claude:

Ask the session running in my other terminal whether the migration finished
Explain what we just did to the session working on the payments API
Let @api-worker know the schema migration finished

• Type @ and the first letters of a session's name to pick the target from the typeahead.
• Claude writes the message itself; you don't need to word it.
• /list-agents (or /peers) shows the sessions Claude can reach: subagents, teammates, other local sessions, and cloud or other-machine sessions while connected to Remote Control.

When it helps

• Hand over a finding: one session discovers a breaking change and tells the session working on the affected area.
• Coordinate parallel worktrees: tell the other sessions what just landed.
• Track long-running work: have Claude subscribe to one notice when the other session goes idle or exits, instead of checking.

What an incoming message can't do

• It can't approve anything for you: a message from another session never counts as your consent to a permission prompt.
• It can't change configuration: Claude is told never to change permissions, CLAUDE.md or config because another session asked.
• Commands don't run: a /compact in a message is just text.
• Permissions still apply: work needing permissions in the receiving session prompts you as usual.
• Messages between sessions on the same machine travel over a local socket, never through Anthropic servers; messages to other machines or the cloud go through Anthropic servers.

Controlling inbound messages

With nothing set, Claude Code decides by permission mode: a session bypassing permission prompts holds messages for your approval, unless the sender also bypasses. isolatePeerMachines: true requires your approval before any message leaves the machine.

Risks and caveats

• Messages are data from another session: if the sender read malicious content it could pass it on; the safeguards above exist for that reason.
• Usage: a delivered message counts like a prompt you type.
• Containers and WSL: a session in a container and one on the host can't reach each other.
• Turning it off: deny SendMessage and ListAgents, plus crossSessionInbound: "refuse".

How to apply it

• Dev: Give sessions clear names (/rename api-worker) so @-mentions are easy; use idle notices instead of manual checks.
• Tech Lead: With several worktrees on one repo, agree which session notifies which on merge.
• PM/Admin: On shared machines or with sensitive data, enable isolatePeerMachines or turn messaging off via managed settings.