Claude Code can now pass a note from one coding session to another. The convenient mental model is a team chat. The safer one is an internal message bus with its own trust rules.
Anthropic added Claude Code cross-session messaging in version 2.1.224. On macOS and Linux, one session can discover another local session with ListAgents and send it plain text with SendMessage. A session can warn another about a breaking schema change, hand over a finding, report a long-running test result, or coordinate work across separate worktrees.
The feature solves a real coordination problem. It does not merge the sessions, transfer files, or lend one session another session’s permissions. Anthropic’s documentation says an incoming message cannot approve a prompt, change configuration, or turn a slash command into an executed command. The receiving session’s permission rules still apply.
What Claude Code actually sends
Payload
Plain text
The receiver gets the message text, sender name, and normally a reply address. It does not receive files or the sender’s full conversation.
Local route
Per-session socket
Sessions on the same machine communicate through a user-restricted socket. They must be able to see the same session files.
Remote route
Replies only
Remote Control lets a session reply to another machine or a web session through Anthropic’s servers. It cannot start that remote exchange.
That scope matters. A text-only handoff is useful for “the migration finished” or “do not use the old field.” It is not a substitute for a commit, an artifact, a test log, or a durable project decision. If the message changes what another agent should build, the evidence still belongs in version control or the system of record.
Delivery has three outcomes, not one
Claude Code checks every incoming message against the receiving session’s inbound controls. The result can be delivered, held, or refused. A held message waits for approval or a later settings change. A refused message is dropped.
Permission boundary
A message is not user consent
The receiving Claude is told that the text came from another session. It cannot use that message to approve a pending action, rewrite permission settings, or change CLAUDE.md. If the requested work needs approval, the receiving session must still ask you.
The defaults also react to permission mode. A session that normally prompts can receive ordinary peer messages directly but holds messages from a sender that says it bypasses prompts. A receiving session that bypasses prompts holds messages unless the sender is in the same permission class. Anthropic caps held messages at 100, accepted unread messages at 50, and expires an unanswered approval dialog after five minutes by default.
The controls builders should know
| Control | What it changes | Practical use |
|---|---|---|
crossSessionInbound | Accepts, holds, or refuses incoming peer messages. | Set an explicit organization or project policy instead of relying on mode-dependent defaults. |
isolatePeerMachines | Requires approval before a message goes beyond the current machine. | Use it where remote sessions cross a meaningful device or network boundary. |
dialogExpiry | Controls how long a held-message approval remains open. | Shorten stale approvals for unattended or shared environments. |
Deny SendMessage | Stops Claude from sending peer, subagent, and team messages. | Disable outbound coordination where the workflow does not need it. |
Deny ListAgents | Stops Claude from discovering reachable sessions. | Reduce unnecessary session visibility. |
Administrators can combine deny rules for SendMessage and ListAgents with crossSessionInbound: refuse. Claude Code still creates the local inbox socket, but it drops messages before they reach the model. Availability also has limits: the feature is not offered on native Windows, Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, or Microsoft Foundry.
Coordination is harder than transport
The Reddit discussion around the launch quickly found the real operational problem: two agents can exchange a warning and still edit incompatible files, repeat work, or disagree about ownership. Messaging reduces copy-paste. It does not create a scheduler, merge policy, source-of-truth hierarchy, or conflict-resolution protocol.
That is the same handoff problem we found in Meta’s overnight Muse Code agents. Persistence makes coordination more valuable and mistakes more durable. It also resembles the policy boundary in Claude Inference Hooks: the useful feature sits directly in the path between intent and action.
A safe rollout for a multi-session repository
The six checks I would run first
- Name every session. Use task-based names and confirm the working directory in
/list-agents, especially when similar names collide. - Assign file ownership. Record which session may change each package, migration, or interface before work begins.
- Make inbound policy explicit. Choose
accept,hold, orrefusefor each environment. - Isolate other machines. Turn on
isolatePeerMachineswhere remote replies require human review. - Log decisions outside chat. Put accepted handoffs in commits, issues, tests, or an architecture record.
- Test denial and expiry. Confirm what the sender and receiver see when a message is held, denied, dropped, or sent to the wrong same-named session.
Long-running headless sessions need extra care. A claude -p worker can receive messages but cannot display the approval dialog. A held message stays held unless a later setting permits it. Setting a broad user-level accept may fix one worker while silently changing every session you run, so prefer the narrowest applicable scope.
My verdict: enable the channel after the ownership model
Claude Code cross-session messaging is a practical upgrade for teams that already run several agents in parallel. It can shorten the time between one session discovering a problem and another session reacting to it. The limits are unusually clear: plain text, per-session permissions, reply-only remote routing, bounded queues, and administrative controls.
The mistake would be to treat a reachable inbox as a coordinated team. Decide who owns each file, which session can receive which class of message, where decisions are recorded, and what happens when delivery fails. Then turn on the transport.
Read the source record
- Read Anthropic’s cross-session messaging documentation.
- Review the Claude Code changelog for versions 2.1.224 through 2.1.226.
- Use the settings reference for inbound, expiry, and isolation controls.
- Read the community discussion as operational reaction, not product documentation.
- Compare the rollout with our Claude migration checklist for fallback and verification discipline.
If one coding agent can interrupt another, what evidence should it be required to attach?
Checked August 8, 2026. Feature behavior and availability are based on Anthropic’s public documentation for Claude Code 2.1.224 and later. The Reddit thread is community reaction, not evidence of product behavior.
