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

URL: https://systemdesignsimple.com/claude-code-sessions-message-each-other/
Published: 2026-11-10
Category: AI Tools
Publisher: System Design Simple (https://systemdesignsimple.com)

## Summary

Claude Code sessions can list the other sessions on the same machine and send them short messages. On one machine a message travels over a local socket owned by your user; across machines it goes through Remote Control and the remote side can only reply. On our Mac on November 7, 2026, one session listed two idle peers by name.

## Key facts

- **Tools:** ListAgents to see sessions, SendMessage to message one
- **Same machine:** Local socket, limited to the owning user
- **Across machines:** Through Remote Control; a cloud session can receive but not message back
- **Our check:** One session saw 2 idle peer sessions, November 7, 2026

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](/claude-code-vs-codex-cli/) 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:

```text
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:

```text
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](/why-an-ai-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.

## Frequently asked questions

**Can two Claude Code sessions talk to each other?**
Yes. A session can list other sessions with ListAgents and send one a short text message with SendMessage. On the same machine the message travels over a local socket.

**Do messages between Claude Code sessions go through the internet?**
Not on the same machine: they use a local socket limited to your user. Messages to sessions on other machines or in the cloud go through Remote Control.

**Can a cloud session message back?**
No. A cloud session receives the message, but it cannot send one back; you read its answer in its own transcript at claude.ai/code.

**Can Claude Code sessions on different machines message each other?**
Yes, where Remote Control is available: the message travels through the provider's servers and the session on the other machine can reply. A cloud session is the exception; it can receive a message but cannot send one back.

## Sources

- [Claude Code docs: Continue local sessions from any device with Remote Control](https://code.claude.com/docs/en/remote-control)
- [Claude Code docs](https://code.claude.com/docs/en/overview)
- [Pasquale Pillitteri: Claude Code sessions can now message each other](https://pasqualepillitteri.it/en/news/10215/claude-code-cross-session-messaging)