What it is and why it matters
Every Claude Code window is a session with a mind of its own. It has its own conversation and only knows what you told it in there. If you open two, by default they know nothing about each other.
The problem is that you become the messenger. One session renames a field in the app, you copy it, paste it into the other window, explain everything again and maybe forget a piece. With two jobs running in parallel, it happens all the time.
Claude Code has a feature just for this: messages between sessions. One session can see the others open on your computer and send one of them a text message. The one that receives it reads it and carries on with it in mind.
Why it matters: you can split the work the way you'd split it between two people. In one you have something built, in the other you ask it to check what the first one is doing. Or one works on the app and the other on the website, and when the first one finishes it lets the second one know. You stay the one who decides, not the mailman.
How to turn it on
Open two Claude Code sessions on the same computer, one per job (for example one in the app's folder, one in the website's).
There's nothing to switch on: if Claude Code is up to date, messages between sessions already work.
Claude has two tools for this: one to see the other open sessions (ListAgents) and one to send a message to one of them (SendMessage). You don't have to type commands: you ask in plain English, like “send a message to the website session”. Sometimes Claude even sends one on its own, when it notices that one of its changes affects the other session's work.
Give each session a name
Sessions find each other by name. Claude Code picks one on its own, but it's easier if you choose it, so you always know which is which.
- In the app window, type /rename app. The name shows up on the bar where you type.
- In the website window, type /rename website.
- In either one, type /list-agents: you see the sessions Claude can reach, with the name to use for each.
When you write to Claude, you can also type @ and the first letters of the name, like @website, and pick the session from the menu. That way it knows exactly who to send the message to.
If your Claude Code doesn't see the other sessions, update it to the latest version and try again. The quickest check: if /list-agents isn't recognized, your version doesn't have this feature yet.
The three ways I use it every day
1. One builds, the other checks
In session 1 I have the feature built. In session 2 I write:
Look at what session 1 is doing. Read the changes it made, try to break them, and if you find a bug, write it to session 1 and to me. Don't touch the files.
The part that matters is “Don't touch the files.” The one checking reads, tests and reports, but doesn't fix. If both of them fixed things, they'd end up editing the same stuff and you'd lose track of who did what. The bug gets fixed by whoever made it, as soon as the message arrives.
2. Passing the baton between app and website
Here the two sessions work in different folders, one on the app and one on the website. In the app session I write:
When you're done and the tests pass, send a message to the website session with what changed (field names, addresses, copy), so it can update its pages.
The message is just text. The other session doesn't see the first one's conversation or files: it reads what it's been sent. That's why I ask for specifics, like field names, addresses and copy, and not a vague “I changed some stuff.”
You don't have to sit there as the alarm clock. If the website session is idle, the message gets it going again. If it's working, it reads the message as soon as it finishes the step it's on, without being cut off halfway.
3. One searches, the other decides
In session 1:
Search the project for every place where login is handled and send the list to session 2.
In session 2:
Wait for the list from session 1, then propose a 5-point plan. Don't write any code until I say ok.
This keeps the deciding session clean: it doesn't fill up with files it read and search results, it only gets the list. And that “Don't write any code until I say ok” leaves you the last word on the plan.
Bonus: get told when the other one is done
If you're waiting on a long job in another session, there's no need to go check every five minutes. In the session you're in, write:
Let me know when the app session has finished what it's working on.
Claude asks the other session to send a notice when it stops, and brings it to you right where you are.
The golden rule
One session, one job. Two sessions on the same file step on each other's toes: if they have to touch the same files, give each one its own copy of the project (they're called worktrees, I talk about them in another video).
A worktree is a copy of the project in its own folder, on its own branch. Each session edits its own copy and leaves the others' alone. The project has to be in git.
To create one, just ask for it, as the first thing in the session:
Work in a new worktree called [name]. Leave the main project untouched.
From the terminal you can also open the session already inside a copy, with claude --worktree followed by the name. Then the messages do exactly this job: when a session finishes its piece, it tells the others what changed.
Common mistakes
- Two sessions editing the same files in the same folder: give each one its own worktree, or let only one of them write.
- Asking the checking session to fix the bugs: ask it to report them, and the session that wrote the code fixes them.
- Vague messages like “I changed some stuff”: ask Claude to write what changed with exact names, because the other session only sees that text.
- Sessions without a clear name: give each one a name with /rename before you start, so you don't write to the wrong one.
- Thinking a message can say yes on your behalf: a message from another session never approves anything, permission requests still come to you.
- Blaming Claude when it can't find the other session: try /list-agents and, if it isn't recognized, update Claude Code.
Checklist
- Two sessions open, one per job
- Each session has a name, set with /rename
- /list-agents shows the other session
- The checking session is told not to touch the files
- Every message says what changed, with exact names
- If they touch the same files, one worktree each
Frequently asked questions
Do the two sessions share their memory?
No. The message is a piece of text one writes to the other, without the conversation and without the files. If you need a whole conversation, resume that session instead of passing it over in bits through messages.
Can they keep writing to each other forever?
No. Claude Code limits repeated messages between two sessions, so an endless back and forth stops on its own. Still, I always give a clear task and a point where to stop.
How is this different from subagents?
A subagent works inside your session, does a piece of the work and reports a summary back to it. Here instead you have two real sessions, opened by you, each with its own window and its own job, writing to each other when needed.
I'm being asked to approve a message. Is that normal?
Yes. It happens mostly when the receiving session runs without asking you for permissions: in that case Claude Code holds incoming messages and asks you first. If you approve, the message goes through.