Message your other Claude Code sessions - Claude Code Docs
Short summary
Claude Code lets your independent sessions message each other to share findings, coordinate work, and report status without you manually copying information between terminals. Messages are delivered between tool calls and filtered through permission controls that prevent sessions from approving actions or changing configuration on each other's behalf. You can prompt Claude to send a message, or it'll detect when another session needs information and send it automatically.
- Claude Code sessions (v2.1.224+, macOS/Linux) can now message each other automatically or on request, using ListAgents/SendMessage tools, without interrupting running processes.
- Cross-machine messaging is one-way by default—remote or web sessions can only reply to existing threads, not initiate them, and replies from sessions without Remote Control arrive without a return address.
- Incoming messages are treated as system info, not user commands, so they can't approve permissions, change config, or run commands—permission prompts still trigger as normal.
- Inbound behavior is configurable per session via crossSessionInbound, with automatic naming (e.g. "myapp-3f") and /list-agents to see reachable sessions.
Full summary
Cross-session messaging in Claude Code lets you send information between independent sessions running on the same machine or across different machines. You need Claude Code v2.1.224 or later on macOS or Linux. The feature works automatically once enabled—Claude can spot when one session has something another needs and send a message without you asking, or you can tell it to send one manually. It uses two tools behind the scenes: ListAgents to find available sessions and SendMessage to deliver messages to them by name.
The main use cases are straightforward: handing off findings when one session discovers a breaking change that affects another, coordinating work across parallel repository branches, getting status updates from long-running tasks like migrations or tests, and replying to messages from sessions on different machines. Messages arrive between tool calls so running processes don't get interrupted. When a session is idle, Claude Code starts a new turn to deliver the message. The receiving session checks each incoming message against its inbound controls, which can deliver it, hold it for approval, or refuse it entirely.
There are real limits on cross-machine messaging. Sessions on the same machine can initiate messages freely because they share the filesystem and register themselves there. Sessions on different machines or the web can only reply to messages—they can't start a conversation. A reply sent from a session not connected to Remote Control goes through to Anthropic servers but arrives without a return address, so the receiver can't answer back. Messages from other sessions also have built-in restrictions: they can't approve pending permissions, change configuration, or execute commands. The receiving session treats them as system-level information, not user directives, so permission prompts still fire if needed.
You can control how permissive each session is with the crossSessionInbound setting. Sessions get names automatically based on their working directory (like "myapp-3f") or you can rename them with the /rename command or --name flag. When sessions share the same name, Claude Code adds a short identifier and shows the working directory in the listing so you can tell them apart. The /list-agents command shows you exactly which sessions Claude can reach from where you are.