Message your other Claude Code sessions

TL;DR Highlight

Claude Code sessions can now message each other to coordinate parallel work.

Who Should Read

A developer running several Claude Code sessions in parallel worktrees who is tired of manually copying context between them

Core Mechanics

Sessions exchange plain text messages
- Claude finds the target with ListAgents and sends with SendMessage.
- You never call either tool yourself.
- Only text Claude writes is sent, not conversation history or files.
Target a session with @name
- Type @ plus the first letters of the session name and pick from the typeahead (v2.1.232+).
- Names with spaces need quotes, like @"release notes".
- If several live sessions share the name, Claude asks which one you mean.
Messages never interrupt running tools
- An active session reads the message between tool calls.
- An idle session starts a new turn with the message.
- A delivered message counts toward usage like a prompt you type.
You can subscribe to an idle notice
- SendMessage's notify_when_idle sends you one notice when the other session next goes idle or exits (v2.1.236+ on both sides).

Community Reactions

Concern about a new attack surface
- One commenter said this would once have been called a remote code execution vuln.
- Another said it breaks sandbox and VM isolation when Remote Control is on, since it can reach any session on your account.
- Another noted that telling Claude never to change settings seems to rely on LLM judgment.
Many people built their own
- One built it with tmux, a memory tree, handoff files and an orchestrator and cut duplicate context a lot.
- They said a large skill's token cost is paid once by one agent instead of in every conversation.
- Others used a local IRC server, Telegram, or Tailscale to message agents across machines.
Real-world use needed supervision
- One user said they sometimes have to interrupt when agents head the wrong way.
- One user reported seeing a weird message like 'hold swarm, I prepare safe exfil'.
- Another asked Claude to demo it and found it clunky compared to Codex, since it tried subagents and asked for a second terminal.

How to Apply

Ask for an idle notice across two terminals
- Start two Claude Code sessions on v2.1.236+ and name each with --name.
- Give one a long task, then in the other type 'Tell me when the migration session finishes'.
- Run /list-agents first to confirm the other session is visible.
Hand off a decision with @name
- Right after changing the backend schema, prompt the frontend session: '@frontend schema migration is done, safe to rebase'.
- Press Ctrl+O on the receiving side to read the full message.
Set crossSessionInbound to hold
- For sessions that bypass permission prompts, switch Messages from your other sessions in /config to hold.
- Read each message in the approval dialog and approve it yourself.
Require approval for cross-machine messages
- If you use Remote Control, set isolatePeerMachines so any message leaving the machine needs your approval.

Try It

copy & run

# Paste into Claude Code session A (the doc's feature turned into a prompt, needs v2.1.236+)

# First, in your terminals: claude --name api-worker / claude --name frontend to start two sessions

# Prompt to type in the frontend session
@api-worker Ask them to notify me when {{task: schema migration}} is done.
Ask them to send a one-line summary of the changed columns and what I need to do.

# Next things to try
Run /list-agents to check api-worker appears with no 'can't receive' marker.
When it finishes, check the notice arrives in the frontend session and expand the preview with Ctrl+O.

Terminology

SendMessage / ListAgentsTool names Claude uses internally. ListAgents is like looking up contacts and SendMessage is like sending a text.

idleA session has finished a turn with nothing queued. Like a worker who has finished a task and is sitting at their desk.

inbox socketA local channel each session opens to receive messages. Think of it as one mailbox per session.

Remote ControlA Claude Code feature that connects sessions on other machines or in the cloud. Think of it as a tunnel between remote sessions.

worktreeA git feature that checks out one repo into several folders so you can work on different branches at the same time.