Claude Code sessions can message each other: how the hand-off works

Claude Code sessions on the same machine can now find each other and send short text messages, so one agent can hand work to another without you copying and pasting. On one machine the message never leaves your computer; it travels over a local socket that only your user can use.

We checked it on our own Mac before writing this, and what follows is what we saw, how the hand-off works, and where it stops.

This article is for developers who already run two or more Claude Code sessions side by side, for example one building a feature and one writing tests. The everyday problem is the hand-off between them: you finish reading one window, copy the important lines, and paste them into the other window with your own summary. Since the sessions can now find and message each other on the same machine, that copying step can go away, as long as the message one session sends is precise enough for the other to act on.

If you also run the other agent, how we use Claude Code and Codex CLI together shows the wider setup these sessions sit in.

What we saw on our machine

On November 7, 2026, we asked the Claude Code session that runs our studio to list its peers. It answered with its own name, the name other sessions use to reach it, and two other sessions:

This session is studio-session-a, the name other sessions use to message it.

Peer sessions (2):
  studio-session-b  ·  interactive  ·  idle  ·  started 3h ago
  other-project     ·  interactive  ·  idle  ·  started 3h ago

We renamed the sessions here; the shape of the answer is exactly what the tool returned. Each peer shows the two things you need before handing it work: whether it is interactive, and whether it is busy or idle.

How do Claude Code sessions send messages to each other?

There are two tools:

• ListAgents lists the sessions this one can message: other local sessions, and, where available, your cloud sessions and Remote Control sessions on other machines.
• SendMessage sends a short text message to one of them by name.

Where the other session runs	How the message travels	Can it answer?
Same machine	Local socket, limited to your user	Yes
Another machine (Remote Control)	Through the provider's servers	Yes
A cloud session	Through the provider's servers	No; read its transcript at claude.ai/code

The local path matters for privacy: two sessions on your laptop coordinate without the messages passing through anyone's servers.

A hand-off that works

The hand-offs that worked for us were small and explicit:

1. Session A builds something, for example an API endpoint.
2. When the tests it wrote pass, it sends Session B one message: what is ready, where it lives, what to do next.
3. Session B writes the client or the docs against it.

Put facts in the message: a file path, a command, a status. The receiving session has only your words to go on, so skip the small talk. A vague "I'm done, take a look" makes the receiving agent guess.

What a good hand-off message looks like

The receiving session starts cold. It knows only what your message says, so write the message like a short ticket:

API ready: POST /orders in src/api/orders.ts.
Tests: npm test -- orders (12 passing).
Next for you: write the client in web/src/orders.ts and a test for the 409 case.
Do not edit src/api/.

Four lines: what is ready, how to check it, what to do next, and what not to touch. The last line matters most when two agents share one repository, because it stops them from editing the same files.

A receiving session starts from your message alone, in the same way an agent works from the history it is given; that is also why an agent re-sends its history when it continues.

When not to use it

• One small task. A single session is simpler; messaging adds a hand-off you have to review.
• Work that needs a decision from you. If the next step needs your judgment, the message should go to you, not to another agent.
• Long instructions. If the hand-off needs a page, write it to a file in the repository and send the path.

The limits

• Messages carry short text only. If the other session needs code, send the file path and let it read the file itself.
• Headless runs (claude -p) cannot show an approval prompt, so a message that needs approval waits there.
• A cloud session cannot reply, so it cannot be the one that hands work back.
• Two agents editing the same files at the same time still conflict. Split the work by folder or by step.

Our take

What changed for us is the hand-off itself. You used to copy text between windows by hand; now an agent writes the message and you review it. That only works if the message is precise. That only works if each message is precise, so the skill to learn is writing hand-offs like good pull request descriptions.

Honest verdict

Good: local messages stay on your machine, sessions show whether they are idle before you hand off, and the tools are plain enough to use without setup.

Worth knowing: cloud sessions are receive-only, approvals still need a person, and parallel edits to the same files need a plan.

What it means for you

Try it with two sessions on one small repo: one builds, one tests. Have the builder send one precise message when it finishes, and read both transcripts afterwards. You will learn more about writing hand-offs from that one run than from any guide.