Claude Code's cross-session messaging feature, shipped in v2.1.224 on August 7, 2026, lets one running session send a plain-text message to another session on the same machine — and Claude can do this on its own, without you asking, when it notices a change that affects what another session is building. You no longer need to copy-paste context between Terminal windows or re-explain your project for the tenth time. It's available on macOS and Linux, messages stay local to your machine (they never touch Anthropic's servers), and the feature is on by default the moment you update.
The catch: only text passes between sessions — never conversation history, files, or permissions. A summary is just a summary, and if session one says "I fixed the pricing page," session two still has to guess which fix, which page, and what changed. The feature automates the handoff that power users have been doing manually for two years, but the quality of that handoff lives or dies on how good the summary is.
- Cross-session messaging shipped in Claude Code v2.1.224 (August 7, 2026)
- Available on macOS and Linux (including WSL 2); not on native Windows
- Messages are plain text only — no files, history, or permissions
- Same-machine messages travel over a local socket, never through Anthropic servers
- Claude can send messages autonomously when it detects a change affecting another session
- The same release removed the 200-subagent-per-session spawn cap
What Is Cross-Session Messaging in Claude Code?
Cross-session messaging is a built-in feature that lets two independently running Claude Code sessions communicate by sending each other short text messages. Before this update, sessions were completely isolated — each one had its own context window, its own task, and no awareness that any other session existed. If you wanted session B to know what session A just discovered, you had to copy the relevant text, switch windows, paste it in, and re-explain the context.
With cross-session messaging, Claude uses two tools to handle the entire flow: ListAgents discovers which other sessions are reachable, and SendMessage delivers a text message to one of them by name. You never call either tool yourself — you just tell Claude what the other session should know, and Claude figures out the target and writes the message. You can prompt it in plain English: "Ask the session running in my other terminal whether the migration finished." Claude finds the right session, composes the message, and sends it.
The receiving session shows the message as a collapsed one-line "Message from" card with a link back to the sender. It processes the message between tool calls — never interrupting running tools — and if the session is idle, a new turn starts. Once delivered, the message counts toward your usage like a prompt.
How Does Cross-Session Messaging Work?
Same-machine messages travel over a per-session Unix socket — a local inter-process communication channel — and never pass through Anthropic's servers. Each session registers itself in files on disk and binds its inbox socket there. Two sessions can reach each other only when they can see the same files, which is why containers with separate filesystems can't talk to host sessions.
Here's how a typical message flow works:
- You start two sessions on related tasks. Maybe session one is updating product descriptions and session two is writing a sale announcement.
- Session one changes a price on your bestseller. Claude notices this change affects what session two is working on.
- Claude sends a message automatically. Without you asking, session one pings session two: "The price on product X changed from $24.99 to $19.99 — update your announcement."
- Session two picks it up mid-task. The message arrives as a card, session two reads it, amends the announcement, and keeps working.
You can also ask Claude to send a message explicitly — "Tell the session working on the API to test the new endpoint I just added" — and Claude handles the discovery, targeting, and delivery.
The same SendMessage tool also handles messaging to subagents and agent-team teammates within a single session or team, which means denying the tool disables all three at once — something to keep in mind if you configure restrictions.
How to Set Up Cross-Session Messaging in Claude Code
There is no setup step. The feature is on by default the moment you update to v2.1.224 or later, as long as you're on macOS or Linux (including WSL 2). You simply:
- Update Claude Code to v2.1.224 or later — run
claude updateor reinstall via npm:npm install -g @anthropic-ai/claude-code. - Open two sessions on related tasks in separate terminal windows on the same machine.
- Verify the feature is active by typing
/list-agents(or its alias/peers). If the command is recognized, messaging is on. You can also check/status— if you see a "Peer address" row, your session's inbox socket is bound and ready. - Ask Claude to message the other session. Use natural language: "Ask my other session what it found on the competitor analysis." Claude discovers the target with
ListAgentsand sends withSendMessage.
If /list-agents isn't recognized, the feature isn't active. The most common causes: you're on a version older than 2.1.224, you're on native Windows, or one of these environment variables is set: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK. The feature is also unavailable on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry.
How Much Does Claude Code Cost?
Cross-session messaging is included in every plan that has Claude Code access — there's no separate fee. As of August 2026, Claude's subscription pricing is:
| Plan | Price | What You Get |
|---|---|---|
| Free | $0 | Claude Code not included |
| Pro | $20/month ($17 annual) | Claude Code, Sonnet + Opus models, ~44K tokens per 5-hour window |
| Max 5x | $100/month | 5x Pro usage (~88K tokens per 5-hour window) |
| Max 20x | $200/month | 20x Pro usage, for heavy all-day sessions |
| Team Standard | $25/seat/month ($20 annual) | SSO, admin controls, Claude Code per seat |
| Team Premium | $125/seat/month ($100 annual) | Higher usage limits for teams |
| Enterprise | Custom (~$20/seat + API usage) | HIPAA, compliance, volume discounts |
Each delivered message counts toward your usage like a prompt, so heavy cross-session coordination will consume your token budget faster. For most small-business and individual workflows running 2-3 parallel sessions, the Pro plan is sufficient. If you're running large multi-agent orchestrations all day, the Max 20x plan at $200/month gives you the headroom.
What Are the Limitations of Cross-Session Messaging?
The biggest limitation — and the one most coverage glosses over — is that messages are plain text only. No files, no conversation history, no structured data, no permissions. If session one says "I fixed the bug in the auth module," session two receives exactly that sentence and has to infer which bug, which module, and what the fix was. Details get lost in compression.
Here's what else you need to know:
- Messages cannot approve permission requests. An incoming message never counts as user consent for a permission prompt. The receiving session's own permission rules still apply to any action the message suggests.
- Commands arrive as text, not actions. If a message says
/compact, it arrives as the literal text "/compact" — it doesn't execute. - Cross-machine messaging is reply-only. A session on another machine or on Claude Code on the web can only reply to messages you send — it can't initiate new conversations through the same channel. Deliveries to other machines route through Anthropic's servers via Remote Control, not the local socket.
- Rate limits apply. Claude Code throttles repeated messages per sender, drops identical repeats arriving in a short window, and caps accepted messages waiting to be read at 50 per session. A message loop between two sessions stops on its own.
- Not available on native Windows. You need macOS or Linux (including WSL 2).
- Name collisions are handled but visible. Two sessions can end up with the same derived name (e.g.,
myapp-3f). The/list-agentsoutput includes each session's working directory to tell them apart.
Cross-Session Messaging vs Subagents vs Agent Teams
Claude Code has three coordination mechanisms now. They serve different purposes and are not interchangeable:
| Feature | Cross-Session Messaging | Subagents | Agent Teams |
|---|---|---|---|
| What it is | Independent sessions you start and steer | Child agents spawned within one session | A coordinated team Claude spawns and supervises |
| Communication | Peer-to-peer messages between live sessions | Report results back to parent only | Teammates message each other directly |
| Context | Each session has its own isolated context | Subagent results return to parent's context | Each teammate has own context; share via tasks and SendMessage |
| Best for | Hand-offs between parallel work you're actively running | Disposable workers for research or verification | Complex multi-step projects needing autonomous coordination |
| Who controls it | You start each session; messages flow between them | Claude spawns and manages them | Claude spawns a lead, the lead coordinates teammates |
Use cross-session messaging when you have two or more ongoing sessions that need to pass live updates — a finding, a status, a breaking change. Use subagents when you want a quick disposable worker that answers a question and returns a result. Use Agent Teams for larger projects where Claude should decompose, coordinate, and synthesize work across multiple agents on its own.
For a deeper dive into building multi-agent teams that your whole team actually uses, see our guide on building a multi-agent AI team for your company.
Can Claude Send Messages on Its Own?
Yes — and this is the sleeper feature. Claude can initiate a cross-session message without you asking when it detects that a change in one session affects what another session is working on. Anthropic's documentation describes this explicitly: "Claude can send a message on its own when it sees the need, for example after making a change that affects work another session is doing."
In practice, this means your AI sessions aren't just able to talk — they're watching out for each other. If session one changes a shared file that session two depends on, session one can proactively warn session two before you even notice the conflict. This is what turns a pile of separate chats into something that behaves like a coordinated team.
That said, Claude decides what to send, and it sends a summary — not your full context. The quality of that summary determines whether the receiving session gets enough detail to act or just enough to be confused. In our testing and in reports from early adopters, summaries work well for simple, concrete changes ("the API endpoint changed from /v1 to /v2") and less well for complex, multi-step modifications where the receiving session needs to know the full chain of edits.
How to Use Cross-Session Messaging for Real Business Work
The feature is technical, but the use cases are practical for anyone using AI for more than casual chat. Here are three workflows that eliminate manual context-handling:
Workflow 1: Research + Drafting Open one session to research a client's industry. Open a second session to draft a proposal. The research session sends findings to the drafting session as it discovers them. The proposal updates in real time. No copy-paste, no context-switch.
Workflow 2: Content + Publishing One session writes a blog post. Another prepares the social media copy and newsletter. When the blog session finishes a section, it tells the social session what the key takeaways are. The social copy builds in parallel.
Workflow 3: Code + Documentation One session builds a feature. Another writes the documentation. When the code session makes a breaking change to the API, it proactively messages the docs session. The docs update before you publish.
For each of these, the key question is: does the receiving session need the raw detail, or just the signal? If it needs files, code, or structured data, cross-session messaging isn't the right tool — use a shared file on disk or resume the session instead.
What This Means for You
If you're a small business owner, freelancer, or builder using Claude Code, cross-session messaging eliminates the most tedious part of running multiple AI sessions: the manual context hand-off. You can now run two or three sessions on related tasks and let them coordinate themselves, at least for simple signals.
But this is one step in a larger trajectory. Single AI assistants were the 2024 story. Teams of AI agents coordinating in real time are the 2026 story. Anthropic's release pattern tells the direction clearly: first agents, then subagents, then Agent Teams, now cross-session messaging. Each step gives AI more autonomy and less need for you to act as a messenger between your own tools.
If you've already been running Claude Code, this is a genuinely good time to experiment. Open two sessions on related tasks, ask one to message the other, and see how the summaries hold up for your kind of work. If you're new to Claude Code, the free setup guide and the agent memory guide for learning from past sessions are the right starting points.
The question is no longer "which AI should I use" — it's "how do I organize my AI team." And if you manage teams of people, you already have the muscle for that.
FAQ
Q: How do I enable cross-session messaging in Claude Code?
A: You don't need to enable anything. Update to Claude Code v2.1.224 or later on macOS or Linux, and the feature is on by default. Type /list-agents to confirm it's active — if the command is recognized, messaging is working. Windows (native) is not supported; WSL 2 is.
Q: Can Claude Code sessions on different machines message each other? A: Only replies. A session on another machine or on Claude Code on the web can reply to a message you send, but cannot initiate a new conversation. Cross-machine messages route through Anthropic's servers via Remote Control, not the local socket. Same-machine messages stay local and never reach Anthropic's servers.
Q: Does a message send my conversation history or files?
A: No. Messages are plain text only — never conversation history, files, or permissions. To move a whole conversation or its full context to another session, use session resume (/resume) instead.
Q: Can another session approve a permission prompt for me?
A: No. An incoming message never counts as user consent for a permission prompt. Commands like /compact arrive as inert text, not executable actions. The receiving session's own permission rules apply to anything the message asks for.
Q: Can I disable cross-session messaging?
A: Yes. Add SendMessage and ListAgents to your permission deny rules to stop sending and listing. Administrators can set crossSessionInbound to refuse in managed settings to drop all incoming messages. A refusing session looks identical to a normal one in /status and in other sessions' listings, so confirm the configuration directly.
Q: Does cross-session messaging work with subagents and Agent Teams?
A: The same SendMessage tool serves all three contexts. Disabling SendMessage removes messaging to subagents, agent-team teammates, and cross-session peers at once. Agent Teams remain a separate feature (gated behind a feature flag in settings) for coordinated multi-agent projects, while cross-session messaging connects sessions you start and steer yourself.
Every claim here is traced to a primary source, dated, and listed under Sources. Research and drafting are AI-assisted; editing, verification and publication are human decisions, and a person is accountable for what appears on this page. How we work →
Discussion
0 comments