Claude Code Cross-Session Messaging: 2026 Deployment Guide

As of August 11, 2026, Claude Code cross-session messaging requires Claude Code v2.1.224 or later, runs on macOS and Linux, and uses ListAgents plus SendMessage to pass text between sessions. The safest deployment path is to validate two sessions on one machine first, isolate every parallel task with a separate Git worktree, and only then connect remote machines. The message channel carries status, decisions, and blockers. It does not carry shared memory, files, conversation history, or permission approval. (Official cross-session messaging documentation)

You should read this if you regularly run multiple Claude Code terminals, ask separate sessions to handle frontend, backend, and tests, or plan to host coding sessions on a remote Mac. If your work is mostly sequential or several agents must edit the same file, stay with one session or use a smaller subagent workflow.

Last updated August 12, 2026. Version and behavior checks are based on the Claude Code release record and official Claude Code documentation.

Before deployment: define the communication boundary

The first mistake is treating cross-session communication as a shared context layer. It is not.

Claude Code sends a plain-text message written by one session to another. The receiving session does not automatically receive the sender’s transcript, files, tool results, branch state, or hidden reasoning. If the receiver needs the full conversation, use session resume instead. If several workers need structured coordination, compare independent sessions with Agent Teams rather than forcing every workflow through SendMessage.

Use cross-session messaging for:

A short implementation decision.
An API or schema change.
A commit or test result.
A blocker that another session must know about.
A request for the current state of a long-running task.

Do not use it for:

Synchronizing file contents.
Replacing Git history.
Sharing secrets or credentials.
Granting tool permissions.
Approving a command in another session.
Reconstructing a complete conversation.

Three hidden costs appear quickly in real deployments:

Context loss: A message can tell the test session that tenant_id changed, but it does not provide every related file or migration detail.
Filesystem divergence: Two sessions can have different branches, worktrees, ignored files, generated artifacts, and local environment variables.
Permission asymmetry: A message from another Claude session is not treated as your consent. The receiver still applies its own permission rules and prompts.

There is also a transport boundary. Same-machine sessions communicate through a per-session local socket. A session on another machine uses Anthropic’s servers through Remote Control. A container and its host may fail to discover each other because each environment has a different filesystem view.

First step: check the version, platform, and provider

For this guide, use Claude Code v2.1.227 or later if that is the approved current release in your environment. The feature baseline is v2.1.224, while v2.1.225 added the ability to initiate conversations with sessions on another machine and included unattended-message handling fixes. Confirm the installed build rather than trusting a package manager cache.

claude --version
claude update

Use the official release record to confirm which build is approved for your team. A newer version is not automatically safer for a controlled platform. If you operate managed developer environments, define an approved minimum version and test upgrades before changing every worker.

The supported operating-system boundary is specific:

macOS is supported.
Linux is supported.
Linux inside WSL 2 is included.
Native Windows Claude Code is not supported for cross-session messaging.
Provider availability is narrower than general Claude Code availability.

The official documentation currently excludes Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, and Microsoft Foundry for cross-session messaging. A session can still run Claude Code through a provider while lacking this feature. Do not assume that successful authentication means ListAgents and SendMessage are available.

Run a capability check inside the session:

/list-agents
/status

If /list-agents is unknown, start with the version, operating system, provider, and feature-flag checks. If the command works but another session is absent, the problem is narrower: naming, permissions, inbound policy, Remote Control, or filesystem visibility.

Second step: validate two local sessions in the first hour

Start with a single macOS or Linux machine. Do not begin with a remote Mac, a container, or an unattended worker. The local test gives you a known transport path and makes failures easier to classify.

Use two directories or worktrees and give the sessions unambiguous names:

/rename frontend-agent

/rename api-agent

You can also assign a name at startup with the supported --name option. Names matter because the agent list may contain sessions from different directories, and two sessions can otherwise receive similar automatically generated names.

Run this validation sequence:

[ ] Open session A in a clean project checkout or dedicated worktree.
[ ] Open session B in a separate checkout or worktree.
[ ] Rename them frontend-agent and api-agent.
[ ] Run /list-agents in both sessions.
[ ] Confirm that each session can see the other.
[ ] Ask session A to send a read-only status request to session B.
[ ] Reply with the current branch, latest commit, and test state.
[ ] Confirm whether the sender reports delivery, holding, or refusal.
[ ] Repeat once while the receiver is busy running a tool.
[ ] Repeat once while the receiver is idle.

A receiving session reads a message between tool calls, so an active tool is not interrupted. If the receiver is idle, Claude Code can start a new turn with the message. The result can be delivered, held for approval, or refused according to the receiver’s inbound controls.

Use a message with a small, testable payload:

Ask api-agent for a read-only status report. Request its branch name, latest commit, and whether the API test suite is passing. Do not ask it to edit files.

This is better than testing with “make the frontend work.” A read-only request proves that routing works without mixing communication failure with code execution, permissions, or merge conflicts.

A realistic first-hour case

Suppose api-agent changes a response field from userId to accountId. It should message:

The API response field is now accountId instead of userId. Commit 4f2c8a1 contains the change. Frontend clients must update before integration tests run.

That message is useful because it carries a decision, a location in history, and a consequence. It is not enough to replace a review. The frontend session still needs to inspect the commit, update its own worktree, run tests, and report any incompatibility.

Third step: create Git worktrees before parallel edits

Cross-session messaging reduces manual copying. It does not prevent two sessions from editing the same working directory.

Use a separate Git worktree for each independently owned task. Claude Code’s worktree workflow is designed to isolate parallel sessions so changes do not collide. (Official worktree guide)

A manual setup can look like this:

git worktree add ../project-frontend -b agent/frontend
git worktree add ../project-api -b agent/api
git worktree add ../project-tests -b agent/tests

Start one Claude Code session in each directory. Keep ownership explicit:

project-frontend: UI and client integration.
project-api: routes, schemas, and server behavior.
project-tests: regression tests and compatibility checks.

The worktree does not isolate everything. Worktrees share the repository object database, and local services may still point at the same database, cache, port, or test fixture. Generated files outside the worktree can also become a coordination problem. Keep shared resources read-only where possible and assign ports or test namespaces when parallel execution requires them.

Send only coordination facts:

“The response field changed.”
“Commit is ready for review.”
“Tests fail because the fixture still expects the old schema.”
“The migration is blocked by a missing environment variable.”
“The branch is ready to rebase.”

Move code through commits, fetches, rebases, and pull requests. Do not paste large files into messages. A long message consumes context while still failing to establish a reliable source of truth.

The main advantages are clear:

Lower risk of direct file overwrites.
Easier rollback by branch.
Smaller messages.
Cleaner review boundaries.
Better attribution when a regression appears.

The limitations are equally important:

A worktree does not prevent overlapping architectural changes.
Shared configuration files still need an owner.
Independent branches can drift from the same base.
Communication cannot detect every semantic conflict.
Integration testing remains mandatory.

For a deeper operating model, connect this workflow with a Git worktree isolation guide when your team is deciding how to structure long-running coding agents.

Fourth step: expand from local messaging to remote machines

Only move to a remote Mac or another machine after local delivery is predictable.

The path changes when the target is remote:

Same machine: the message travels over a per-session socket and does not pass through Anthropic’s servers.
Another machine: the message travels through Anthropic’s servers over the target machine’s Remote Control connection.
Claude Code on the web: the message travels through Anthropic’s servers to the cloud session.

Starting a conversation with a session on another machine requires v2.1.225 or later, and the target must appear in the agent listing. The source session also needs the relevant Remote Control connection. If the target is not connected, you may be able to send a one-way request without a reply address, but the receiver cannot answer through the same path.

Validate the remote path with non-sensitive content:

Send the remote api-agent a test message containing only:
REMOTE_LINK_TEST
Reply with the session name, current repository folder, and whether replies are enabled.

Check four conditions before sending project information:

The remote session name is unique.
The target working directory is the expected one.
The reply address is present.
Disconnecting and reconnecting produces a visible, understandable state.

Containers require extra care. Claude Code discovers local sessions through files and sockets. A host session and a container session may not see the same discovery files, so /list-agents can appear incomplete even when both processes are running. Two sessions inside the same container can communicate if they share the expected filesystem and socket view.

Remote Control is not the same as session resume. Remote Control lets you reach and steer a running session from another device. Session resume restores a conversation and its context. Cross-session messaging sends a targeted text update. Choose the mechanism according to the job instead of combining them by habit.

FAQ: deployment questions that decide the design

How should two Claude Code terminals exchange a message?

You normally describe the task in natural language. Ask one session to check another session’s status or pass along a specific finding. Claude Code uses ListAgents to identify reachable sessions and SendMessage to deliver the text. Use /list-agents when you need to inspect visibility yourself. Clear names and separate worktrees make the result easier to trust.

Which systems are supported?

macOS and Linux are the supported operating systems, including Linux inside WSL 2. Native Windows is outside the feature’s supported range. The provider also matters. If you use a supported operating system but an excluded provider, the commands may be unavailable or the target session may not appear.

How do multiple sessions avoid touching one file?

Use a Git worktree per task and assign ownership before starting. If frontend and backend both need to change a shared schema, make one session the owner and send the contract change to the other. Merge through Git and run integration tests. Messaging tells agents what changed; it does not lock arbitrary files or resolve semantic conflicts.

Does remote messaging use a server?

Yes. Same-machine messages use local sockets. Messages to another machine or a web session use Anthropic’s servers and depend on Remote Control connectivity. Set isolatePeerMachines when every cross-machine message must receive human approval before leaving the current machine.

Why does SendMessage fail or disappear?

Check version, provider, /list-agents, /status, and the receiver’s inbound policy. A message can be held or refused. SendMessage and ListAgents can also be denied by permission rules. A container boundary, missing Remote Control connection, duplicate session name, or a non-interactive session without the expected socket can produce the same symptom.

Fifth step: tighten inbound controls before production use

Treat inbound messaging as an input boundary, not as a trusted internal command bus.

The receiver can set crossSessionInbound to:

accept: deliver incoming messages to Claude.
hold: show a notice and wait for approval.
refuse: drop incoming messages without delivery.

For an interactive development session, accept may be reasonable when the sender and receiver are both under your control and worktrees are isolated. For a session running with bypassed permission prompts, hold is a safer default. For sensitive repositories or isolated projects, use refuse.

Require approval for cross-machine messages with:

{
  "isolatePeerMachines": true
}

This setting requires approval before a SendMessage request leaves the machine, including when the sending session uses a bypass-permissions mode. (Official settings reference)

To disable the feature for a sensitive project or organization:

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

The permission model makes an important distinction: a received message cannot approve a command, change configuration, modify CLAUDE.md, or execute a slash command. Text such as /compact arrives as text, not as an executable instruction. The receiving session’s own permission prompts still apply.

Use this policy split:

Interactive session: accept for local peers, hold for remote peers.
Bypass-permission session: hold by default; never allow blind remote instructions.
Unattended worker: accept only with a narrow task, isolated worktree, bounded tools, and explicit logging.
Sensitive project: refuse, plus deny SendMessage and ListAgents.

Agent Teams deserve separate treatment. They provide a lead session, independent teammates, a shared task list, and direct teammate messaging. Subagents are different: they report back to the main session and do not communicate laterally. Independent cross-session messaging is best when you started and steer separate sessions yourself. (Agent Teams documentation)

First week: measure coordination instead of assuming value

Run the workflow for several days before expanding it. Record:

Messages sent.
Delivered, held, refused, and expired messages.
Human approvals per task.
Duplicate notifications.
Conflicts found during rebase or integration.
Time sessions spend idle while waiting for another session.
Number of messages that required a follow-up clarification.
Test failures caused by stale interface assumptions.

You do not need a complex observability system at first. A small log with the session name, worktree, timestamp, message type, outcome, and resulting action is enough to expose coordination waste.

Scale up when:

Tasks are independently owned.
Agents exchange short, high-value updates.
Worktrees stay clean.
Remote sessions remain discoverable.
Approval prompts are predictable.
Integration failures decrease rather than multiply.

Return to one session or a subagent model when:

Work is mostly sequential.
Agents repeatedly edit the same files.
Messages outnumber meaningful code changes.
The receiver needs the sender’s entire context.
Human approval becomes the bottleneck.
Remote connectivity creates more diagnosis work than development value.

Agent Teams consume more tokens and add coordination overhead. Parallelism is useful when work can proceed independently, not when every step depends on the previous agent.

When a remote Mac becomes the better operating environment

A personal laptop is convenient for a short local test, but it becomes a poor host when several Claude Code sessions must remain online across time zones. Sleep states, changing networks, limited terminal visibility, accidental project switching, and local resource contention all make handoffs harder to audit.

A remote Mac is a better fit when you need:

Persistent sessions while your laptop is offline.
A stable macOS environment for Apple-platform work.
Separate worktrees for frontend, backend, and test agents.
A fixed network location for Remote Control.
A repeatable handoff process between developers.
Long-running sessions that should not compete with your daily machine.

That does not mean renting a remote Mac is always the right answer. A stable, heavy workload may justify buying dedicated hardware. A project requiring physical USB devices, local simulators, or private network access may also need a machine you control directly. For temporary testing, migration work, or a short AI coding sprint, however, renting can avoid the setup and maintenance burden of a permanent host.

If your current setup relies on a personal Mac, it has three practical weaknesses: sessions disappear when the machine sleeps, multiple worktrees compete with interactive development, and remote handoff depends on whichever network and terminal state you left behind. In that situation, a rented environment from kvmsync can give you a cleaner place to keep Claude Code sessions, worktrees, and Remote Control connections online without turning your daily laptop into a permanent build server. Review the remote Mac deployment guidance and capacity planning resources before choosing an environment.

The right decision is conditional: validate local communication first, keep code movement in Git, and use a remote Mac only when persistence, separation, or cross-time-zone access solves a problem your current machine cannot handle.

FAQ

How do I send a message between two Claude Code terminals?

Start two supported Claude Code sessions, give them clear names with `/rename` or `--name`, and confirm visibility with `/list-agents`. Then ask the sending session to check the other session’s status or pass along a decision. Claude Code uses `ListAgents` to find the target and `SendMessage` to deliver text. You do not normally call either tool manually.

Which operating systems support Claude Code cross-session messaging?

The feature is officially available on macOS and Linux, including Linux inside WSL 2. It is not available in native Windows Claude Code sessions. Provider support also matters: the official documentation excludes Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, and Microsoft Foundry for this feature.

How can multiple Claude Code sessions avoid editing the same file?

Give each session its own Git worktree and assign ownership by area, such as frontend, backend, or tests. Use messages only for interface changes, commit status, test results, and blockers. Worktrees isolate file edits, but they do not replace review, rebasing, integration testing, or ownership rules for shared configuration files.

Does Claude Code cross-machine messaging go through a server?

Yes, when the target runs on another machine or in Claude Code on the web, the message travels through Anthropic’s servers over the relevant Remote Control connection. Same-machine messages use a per-session local socket and do not pass through Anthropic’s servers. Cross-machine replies also depend on the target session having a usable reply address.

What should I check if SendMessage does not arrive?

Check the sender and receiver versions first, then run `/list-agents` and inspect `/status`. Confirm that the target appears, `SendMessage` and `ListAgents` are not denied, inbound handling is not set to `hold` or `refuse`, and Remote Control is connected for another machine. Containers can also hide sessions because host and container filesystems do not share discovery files.