I run three Claude Code terminals on busy client repos more often than I admit. Backend in one window, integration tests in another, a migration script in a third. When the migration renames a column, the API session keeps building against the old schema until I notice and paste a warning by hand.
Cross-session messaging, shipped in Claude Code v2.1.224, closes that gap. Independent sessions can exchange short plain-text notes through first-party tools, with permission-aware delivery and rate limits so two agents cannot ping-pong forever.
This is not agent teams (Claude supervising spawned workers inside one session). It is closer to Slack between terminals you already opened.
What actually shipped
Anthropic added two tools under the hood:
| Tool | Role |
|---|---|
ListAgents | Discover subagents, teammates, local sessions, cloud sessions, and Remote Control targets |
SendMessage | Deliver a plain-text message to a named session |
You prompt Claude in plain language. It writes the message itself. Example from the docs:
Explain what we just did to the session working on the payments API
From v2.1.232 onward you can @-mention a session by name (@api-worker) the same way you mention subagents, skipping a full list when you already know the target.
How delivery works (and what can go wrong)
The receiving Claude reads inbound text between tool calls during an active turn, so a running shell command is not interrupted. If the session is idle, Claude Code starts a fresh turn with the note.
Each receiving session applies crossSessionInbound settings: accept, hold, or refuse. When unset, behavior derives from both sessions' permission modes. A bypass-permissions sender talking to a prompting receiver typically lands in hold until you approve. Dialogs default to a five-minute expiry. Inboxes cap at 100 held messages (oldest dropped) and 50 delivered messages per session.
Anthropic also throttles loops: repeated identical sends drop, and delivery is not guaranteed if the target inbox is full or a safety check fails (symlinked socket, wrong process, etc.).
That honesty matters. A live channel between semi-autonomous sessions is a new attack and mistake surface. Permission boundaries stay per session. Claude is instructed not to ask a peer to run something its own session would block.
When I use it vs agent teams or resume
| Pattern | Tool |
|---|---|
| Continue the same conversation elsewhere | /resume a session |
| Claude spawns and supervises parallel workers | Agent teams |
| You opened separate terminals and want handoffs | Cross-session messaging |
| Watch many sessions from one UI | Agent view |
| CI or chat pushes events in | Channels |
I still reach for dynamic workflows when one orchestrator should fan out hundreds of subagents inside a single job. Cross-session messaging fits the messier reality: three human-steered terminals on the same repo, maybe in separate git worktrees.
Cross-machine and idle notices
From v2.1.225, Claude can message your Claude Code on the web or Remote Control sessions when they appear in ListAgents. Starting a conversation to another machine requires that listing path.
v2.1.236 adds notify_when_idle: one session can subscribe to a single notice when a long migration or test run on this machine goes idle or exits. One shot, 12-hour timeout, no polling tax on either side.
Availability gaps to plan around
Cross-session messaging needs Claude Code v2.1.224+ on macOS/Linux (WSL 2 counts). Native Windows needs v2.1.234+.
It is not on Amazon Bedrock, Google Cloud Agent Platform, or Microsoft Foundry. If your org routes Claude Code through hosted inference, assume this feature is off until Anthropic extends it.
Run /list-agents to see names your sessions answer to. The first row is this session's name; others are reachable targets.
A practical setup I use on client repos
- Name sessions by surface, not by date.
api-worker,migration,e2e-testsbeatssession-3. - Keep permission modes aligned across parallel terminals. Mixed bypass + prompting pairs create approval holds you did not intend.
- Commit before cross-session handoffs so the receiving session can diff against git, not trust a summary alone.
- Use idle notices for migrations that run longer than your attention span, instead of tab-switching every few minutes.
What this changes for applied AI shipping
The solo terminal era was always a lie for serious refactors. You already ran multiple agents. You just acted as the message bus.
Cross-session messaging makes that bus explicit, local, and permission-aware. It does not replace governance: production deploys still need review, vaults, and the kind of scheduled agents I covered in Anthropic scheduled Claude agents.
For day-to-day shipping, though, I would rather Claude warn my test session about a breaking schema change than watch me paste the same paragraph for the fifth time this week.
If you are wiring multi-session agent workflows for a team and want a second pair of eyes on permission boundaries, book a free discovery call.