SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-11-06

How Claude Code Sessions Dey Message Each Other

Learn how Claude Code sessions use ListAgents and SendMessage on one VPS, which versions support am, when a second session helps, and why messages dey held.

Wetin e mean for Claude Code sessions to send message give each other

Two Claude Code sessions fit send message give each other if dem dey run for the same machine, under the same operating system user. One message na just plain text wey one Claude write give another one. E no get conversation history and e no get files. Claude go find the other session with the ListAgents tool and deliver the text with SendMessage, so you no go ever need call any of the tools by yourself. You just talk wetin the other session need know, and Claude go write the message by itself.

Dem dey call this feature cross-session messaging. As of November 2026, e need Claude Code v2.1.224 or later for macOS and Linux, including Linux wey dey inside WSL 2, and v2.1.234 or later for native Windows. Messaging between sessions for the same machine dey work for every provider, including Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry, where e need v2.1.248 or later. To reach your sessions for other machines or for cloud dey more restricted: e dey pass through Remote Control, wey need claude.ai sign-in, so e no dey work with API key or for those four providers. When a session meet those requirements, messaging don already dey on and nothing dey to enable. The behaviour wey we describe below come from the Anthropic documentation for cross-session messaging.

VPS na where this matter dey important, because VPS na where sessions dey stay long enough to make sense to talk to dem. For laptop, you go close the lid. For server under tmux, session wey you start on Monday still dey run on Thursday, still hold the context of one repository. Once you get two of those, how dem take dey talk no be theory again. If you never set that one up, start with running Claude Code on a VPS under tmux, wey cover the session plumbing wey this guide dey assume.

When second session worth the tokens

Start with the cost. Each session na separate Claude instance with im own context window, so two sessions go cost roughly twice wetin one go cost for the same period. Message wey dem deliver count toward usage exactly like prompt wey you type. Coordination no be free, and work wey really be one sequence of steps go slower and cost more when you split am across sessions.

The cases where second session pay for itself get one common pattern. Two pieces of work run at the same time without waiting for each other, and one of dem learn something wey the other need during the task.

  • One session find breaking change while the other dey build on the code wey e break. Claude summarise the change and send am, instead make you type am again for the other terminal.
  • Two sessions work on the same repository for separate git worktrees, and one need know wetin land.
  • Long migration or test run report the result back to the session wey you dey watch.
  • One builder session and one reviewer session, where the reviewer read wetin builder produce and send back wetin e find.

When the work dey sequential, or when both sessions go edit the same files, use one session. When you want coordinated group wey Claude spawn and supervise inside one task, na agent teams be that, and e be separate feature wey still dey experimental. When na only the same conversation you want for another terminal, resume the session instead. Cross-session messaging na for independent sessions wey you start and control by yourself.

Check say the feature dey before you plan wetin you wan do

First, check the version:

claude --version

Compare the number with 2.1.224. Then, inside one session, type /list-agents, wey still dey respond to /peers. E go print every agent wey that session fit reach, plus the name wey each one dey answer to. If the system no recognize the command at all, e mean say that session no get cross-session messaging, and no crossSessionInbound value fit change am. Type /status and look for one Peer address row: e get the inbox address for that session, wey start with uds:.

One wahala dey wey dey catch VPS users for old builds. Before v2.1.248, messaging for the same machine depend on feature-flag fetching, and plenty privacy variables dey switch that fetching off, wey come leave the feature for e default off state. DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, and DISABLE_GROWTHBOOK all dey do this. People dey harden new server by pasting those ones inside ~/.bashrc, then dem go wonder why /list-agents no dey. From v2.1.248, messaging between sessions for the same machine dey work even if fetching off, so updating na the better way to fix am. The variables still dey important for sessions wey dey outside this machine: if fetching off, Claude fit reach those ones only when Remote Control dey available, and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC plus DISABLE_GROWTHBOOK dey make Remote Control no dey available. The same values fit come from the env map inside one settings file or from managed settings, so check the shell first.

env | grep -E 'DO_NOT_TRACK|DISABLE_TELEMETRY|DISABLE_GROWTHBOOK|NONESSENTIAL'

For old build, unset any one wey print. For DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, any value wey no empty dey turn the behaviour on, even the string 0, so DISABLE_TELEMETRY=0 no dey do wetin e be like say e dey do. You go turn am off by unsetting the variable or setting am to empty string.

Give your sessions name so you fit know dem apart

Claude dey address message to session by name, but you no must set one. If you no set am, Claude Code go name the session by e-self, and Claude fit still find that session with ListAgents and send message go there with SendMessage. For interactive session, the automatic name dey join the working directory name with two-character suffix, like myapp-3f. That one dey okay for one session but e dey confuse if you get four, and two sessions fit end up with the same name. To choose the name by yourself, set am when you start the session:

claude --name builder-api

You fit also set am with /rename inside session wey dey run. Unless the session dey connected to Remote Control, the /list-agents output dey show each local session working directory, wey dey help you know sessions wey get same name, and Claude own listing dey add short identifier to the address when names clash. While the session dey connected to Remote Control, /list-agents dey commot working directories and any session name wey e no fit link to person, so that kind row go read (unnamed session). Wetin Claude dey see when e dey look for target no dey change. To name dem by yourself dey cheaper pass make you dey read identifiers. Name wey you choose self dey make the @ typeahead useful: from v2.1.232, if you type @builder for prompt and pick the session, you don tell Claude exactly which session you mean.

Two session tmux layout wey you fit reproduce

Dis one na builder session and reviewer session for one repository. Di reviewer dey work for separate git worktree, so di two no go ever write di same file. git worktree add with HEAD dey give you detached checkout, wey be exactly wetin you need for session wey dey read instead of commit. Because di two sessions dey do different work, e good make you give di reviewer one output style wey be im own, wey go change dat session system prompt so e go stay for every turn instead of fade like instruction wey you type one time.

cd ~/src/api
git worktree add ../api-review HEAD
tmux new-session -d -s agents -n builder -c ~/src/api
tmux new-window -t agents -n reviewer -c ~/src/api-review
tmux send-keys -t agents:builder 'claude --name builder-api' C-m
tmux send-keys -t agents:reviewer 'claude --name reviewer-api' C-m
tmux attach -t agents

Ctrl+b then w go list di windows by name so you fit pick one. For di builder window, run /list-agents. You suppose see reviewer-api with im working directory ~/src/api-review. If e no dey, di reviewer session never finish start, or one of di two problems for di next section dey happen. Den hand something over wit plain language:

Tell reviewer-api which files I changed for the rate limiter and what to look at first.

Claude go write di summary and send am. You no go write di message text, and wetin Claude send dey vary. For di reviewer window, di message go show as dim one-line preview wey carry di sender name and di first line of di text, like › Message from @builder-api: …. If dat session dey idle, Claude go start new turn for am sharp sharp. If e dey mid-turn, di message go wait until between tool calls, so running command no go ever interrupt. Ctrl+O go open di transcript viewer with di full text, and Claude go read di whole message weda you expand am or not. Di pair dey work better when di builder keep im changes small, because narrow diff dey make hand-off short and review wey di other session fit finish for one turn, na di habit wey the lazy senior dev skill dey enforce.

Who fit see who for one VPS

Delivery wey happen for the same machine no dey pass through Anthropic servers. Each session dey bind its own inbox socket. Na Unix domain socket be this, and e get path for that machine filesystem. Session go only show for listing of your other sessions when e bind one. Two things follow from this, and both fit cause wahala for server.

The socket dey restricted to your operating system user. Session wey you start as root and session wey you start as deploy no fit see each other, even if dem dey side by side for the same tmux server, because session wey belong to one user no fit reach another user's socket. Run both sessions as the same user.

Container get its own filesystem. Session inside Docker and session for the host no fit reach each other. Two sessions inside the same container fit message each other normally. If you keep agents inside containers for isolation, like how to run coding agents inside disposable VM, expect messaging to work inside a container but not across the container boundary.

Your sessions for other machines, and your cloud sessions, go show for the listing only while this session dey connected to Remote Control. Sessions for other machines get label Remote Control. From v2.1.225, Claude fit start conversation with a session for another one of your machines, not only reply to one. Those messages dey pass through Anthropic servers, and messages to cloud session dey pass through dem too. Cloud session no fit answer with SendMessage, even when the message carry reply address. The message still dey arrive, and you go read the cloud session response for its transcript at claude.ai/code. If this session no dey connected to Remote Control when Claude sends message beyond the machine, the message still go go, but e no go get reply address, so the other side no fit answer am.

Why your message never reach

The reason wey dey always happen no concern network. The session wey suppose receive the message decide wetin e go do with am, and the decision na make e no deliver am. Every message wey arrive dey end up in one of three ways: dem deliver am, dem hold am (dem keep am aside until you approve am), or dem refuse am (dem drop am without delivery).

When no crossSessionInbound value apply, Claude Code dey decide per message by comparing the permission modes of the two sessions. E dey group sessions wey dey bypass permission prompts into one class, and every other session into the other. auto, acceptEdits, and dontAsk dey count as prompting. Plan mode dey count as bypassing if you dey inside interactive terminal session wey get bypass permissions available. If you no sure which class a session belong to, wetin each permission mode actually dey do na better thing to read first, because auto na where most sessions dey start now and e dey the prompting side of that split. The rule come be symmetric:

  • A receiving session wey dey prompt for permissions dey deliver every message. E dey only hold message if the sending session identify itself as one wey dey bypass prompts.
  • A receiving session wey dey bypass prompts dey hold every message for your approval. E dey only deliver message if the sender sef dey bypass.

So the first workflow wey most people dey build na exactly the one wey no dey work. You go start builder with --permission-mode bypassPermissions because you want make e run unattended, you leave the reviewer for defaults, and every message wey the builder send go dey wait for approval dialog wey nobody dey watch. That dialog go close after the dialogExpiry deadline, wey default to 5m, and the message go drop. Check the screen of the receiving session for pending approval dialog before you blame the socket.

To make session take messages unattended, set crossSessionInbound to accept. Where you set am go decide whether e go apply. Claude Code dey read managed settings first, then the --settings flag, then user settings, and e dey apply the first value wey e find. Value wey dey project or local settings dey apply only when e stricter, follow this ladder accept < hold < refuse. accept inside .claude/settings.json dey looser pass anything, so dem dey ignore am anytime wey trusted source don set value. Put am inside ~/.claude/settings.json, or pass am for one session. From v2.1.232, the /config row Messages from your other sessions dey write the same user setting for you.

claude --name runner --settings '{"crossSessionInbound":"accept"}'

Headless claude -p worker dey bind inbox socket like interactive session and e go show for listing, but e no fit show approval dialog. Claude Code dey keep message hold there for the same dialogExpiry deadline, five minutes by default, e go deliver am if mode or settings change allow am within that time, otherwise e go drop am and report am as expired to any sender wey e fit reach. The --settings line wey dey up there na how you go let such worker take messages. Session wey you start for bare mode no dey bind any socket at all, so e no fit receive messages and e no fit show for the list.

Where hand-offs dey deadlock

Message loops na something wey dem don handle for you. Claude Code dey rate-limit messages wey repeat per sender, e dey drop identical messages wey come within short time, and e dey cap messages wey dey wait to be read for 50 per session, so loop between two sessions go stop by itself. Held messages no fit pass 100, and the oldest ones go drop once e pass that number. From v2.1.238, when session inbox drop your message because of rate limit or full queue, e go tell your session.

The failure wey dey happen dey quiet, and na hand-off e be, no be loop. Session A ask session B question wey e need answer before e fit continue, then e go idle. B hold the message, or B dey middle of long work, or B answer question wey A no really ask. A go wait. You go come back after one hour meet two idle sessions and no work done.

Write hand-offs wey no need reply. Good message dey carry fact or decision: wetin change, and wetin be the result. Bad message dey ask the other session for permission, or for answer wey the sender dey wait for. Claude don get instruction say make e no ask another session for action wey e own permission settings go block, and make e route that work back to you instead. Extend that rule yourself. If session no fit make progress without answer, na you suppose answer am. If one session only need know when another finish long task, ask for notice instead of reply: from v2.1.236 for both sessions, Claude fit ask one of your sessions for this machine make e send back single notice when e next go idle or exit, and Claude Code go drop that request after 12 hours if nothing show. Context discipline help here too, because session wey lose the thread go write vague messages; managing context in Claude Code cover that side.

Treat incoming message as untrusted input

Claude Code dey tell the Claude wey dey receive say the message come from another session, no be from you, and e dey limit wetin that message fit do. Na the program wey wrap the model dey enforce this, no be say the model just decide to obey; na this be the practical difference wey an agent harness dey make. Message no fit answer pending permission prompt on your behalf, because consent from another session no be your own consent. E no fit change permission settings, CLAUDE.md, or any other configuration because another session ask am. Slash command inside the text, like /compact, go arrive as plain text and e no go ever execute. If the work wey you wan do with the message need permission wey the receiving session no get, you go see the same prompt wey you for see for any other work. When the sending session dey run for auto mode, e classifier sef dey review every message before Claude Code deliver am, and any message wey e block no go ever reach the recipient. These limits dey work even for permissive modes, na why session wey dey bypass dey hold inbound messages by default instead of to trust dem.

That one cover permissions. E no cover content. The sending session fit don read pull request description, web page, dependency README, or issue comment wey stranger write, and anything wey e read fit shape the text wey e go write give your other session. The message na data. You suppose treat am with the same suspicion like any other text wey enter session from outside. This na the discipline wey dem describe for keeping secrets out of your AI agents: assume say anything wey cross trust boundary fit be wrong, and make you no ever allow am authorize itself.

Two controls dey if you want reduce this one. If you set crossSessionInbound to refuse, e go drop inbound peer messages without delivering dem, and from project or local settings, that value dey override every other source, because na the strictest one for the ladder. To stop this session from sending or listing, add permission deny rules wey name SendMessage and ListAgents, write dem as bare tool names without any specifier. If you set isolatePeerMachines to true, e go require your explicit approval before any message reach session wey dey outside this machine, and that approval dey required even for bypassPermissions mode.

{
  "crossSessionInbound": "refuse",
  "isolatePeerMachines": true
}

If you deny SendMessage, e go also remove messaging to subagents, because the same tool dey serve both. Session wey dey refuse no go show any visible change for e own /status or for the listings of other sessions for the same machine, so confirm the setting from the session configuration instead of the screen.

Bridges and shared memory MCP servers

Plenty third-party projects show for the same period with related work: local agent-to-agent bridges wey dey relay text between agents wey dey run, and MCP (model context protocol) servers wey give several agents one shared store to read and write. Treat dem as different design, no be competitor, and verify any install command against the project own README before you run am. Messaging na push, because sender dey put text inside receiver turn. Shared store na pull, because nobody dey interrupt and session go see the note when e next check. Pull dey calmer for status wey dey change slowly, and e only work when session actually check am.

If you choose this approach, the important questions concern the process, no be feature list. Which user the server dey run as, and wetin e fit read for the box. Running MCP servers for VPS explain that setup. Sharing agent skills across repos explain the simpler case where wetin you want share between sessions na instructions instead of live state, and e remove plenty messages wey you for otherwise send. For the bigger picture, running coding agent for VPS na the place to start.

FAQ

Why no recognise for my session?

The session no get cross-session messaging. Check claude --version first: the feature need 2.1.224 or later for macOS and Linux, 2.1.234 or later for native Windows, and 2.1.248 or later for Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry. For build wey older than 2.1.248, also check your shell for DO_NOT_TRACK, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, or DISABLE_GROWTHBOOK, because each one of dem dey off the feature-flag fetching wey older builds need for messaging. If you update to 2.1.248 or later, sessions for the same machine no longer depend on am.

Why my message to the other session no ever reach?

If /list-agents dey work, messaging dey on and na something more specific stop that message. Permission modes na the common cause. A session wey bypass permission prompts go hold every inbound message for your approval unless the sender dey bypass too. That approval dialog go expire after the dialogExpiry deadline, wey be five minutes by default. Check the receiving session for pending approval dialog. To fix am, set crossSessionInbound to accept inside ~/.claude/settings.json or pass am with --settings, because accept for project or local settings dey ignored as the looser value.

Claude Code session for Docker fit message one wey dey host?

No. Each session inbox na socket for that machine filesystem. Container get its own filesystem, so session inside the container and session for host no fit reach each other. Two sessions inside the same container fit message each other normally. Similar rule explain why session wey dey run as root and session wey dey run as your normal user no fit reach each other: socket dey restricted to the operating system user wey own am.

Message from another Claude Code session safe to act on?

Treat the text as untrusted input, because the sending session fit don read web page, README, or issue comment wey another person write. Claude Code already stop the message from acting by itself: e no fit approve pending permission prompt, e no fit change permission settings or CLAUDE.md when request am, and slash command inside the text go arrive as plain text and never run. Those protections cover permissions, no be judgement, so read wetin arrive before you tell the receiving session to act on am.

Cross-session messaging dey send my code go Anthropic?

Between two sessions for the same machine, no. The message dey travel through per-session socket for that machine and never pass through Anthropic servers. Only the text wey Claude write dey send, never conversation history or files. Messages to session for another of your machines, or to cloud session, dey pass through Anthropic servers. From v2.1.225, Claude fit start conversation with session for another of your machines, no be only reply to am. Cloud session go receive the message but e no fit answer am with SendMessage, so you go read the response for its transcript at claude.ai/code. Set isolatePeerMachines to true to require your approval before anything commot from the machine.

Dis article help you?