I ran two Claude Code sessions against one repository and assumed the hard part was coordination. It is not. The hard part is that coordination looks like it solves a problem it never touches.
What is actually built in 🧐
Two sessions can find each other and talk. Anthropic's docs on cross-session messaging describe it: one session warns another that a change broke what it was building on, or answers a question the other was blocked on. Claude uses two tools for it, ListAgents to see who is reachable and SendMessage to write to one of them by name. Nothing to switch on. You check what a session can reach with /list-agents, also spelled /peers.
There is a version floor. Cross-session messaging needs Claude Code 2.1.224 or later on macOS, Linux and WSL 2, and 2.1.234 or later on native Windows. Below that the command is not recognised at all.
The sentence that changes the plan
From the same page: "A message is a piece of text one Claude writes to another, never the sender's conversation history or files."
Text. Not files.
So two sessions can be perfectly informed about each other and still be pointed at the same schema.ts in the same folder, both about to write it. Anthropic says this outright: two agents editing one file in a shared working directory can overwrite each other's changes. There is no source-file locking underneath, and no merge layer doing the reconciling.
Messaging is a channel. It was never a lock.
What actually protects the work
A worktree per session. claude --worktree backend in one terminal and claude --worktree frontend in another, and each session gets its own directory, its own branch and its own copy of the tracked files. The docs put the effect plainly: edits in one session never touch files in another. Claude Code also refuses an edit aimed from inside a worktree back at the main checkout, so the isolation is enforced rather than agreed.
Add .claude/worktrees/ to .gitignore while you are in there, or the worktree contents turn up as untracked noise in your main checkout.
Now messaging becomes the thing it is good at. Session A changes the API, makes a small commit, and sends session B the commit hash and the list of files that moved. B rebases or cherry-picks, then re-reads what changed. If both of them touched the same file, git raises a conflict. A conflict interrupts you. A silent overwrite is a loss you find out about later, if at all 😬
The part no tool does for you 🤔
Worktrees do not decide who owns package.json.
For the files both sessions genuinely need to change, the only reliable scheme is boring: one owner at a time. Different files in parallel, the same file in sequence. Write it into the prompt as a protocol. Name the directories each session owns, require a handoff through a message before either one touches a file the other holds, and require a commit before the handoff.
The two alternatives, and why neither replaces this
Agent Teams is the experimental mode where one lead session spawns and supervises teammates, behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. It gives a shared task list, a mailbox, and direct messages between agents, and claiming a task is protected by a file lock. Read that last part slowly: the lock is on the task record, not on the source files. It coordinates who does what. It does not stop two writers landing on one file, which is why the recommendation is still to split responsibility by file.
MCP Agent Mail is the closest third-party attempt: persistent agent identities, an inbox and outbox with threads, file reservations by path and glob, TTL on stale reservations, and an optional pre-commit or pre-push guard. It is the only one of the three that models file ownership at all. But those reservations are advisory. The server reports the conflict, it is not a transactional write lock, and the guard can block a commit without stopping a write already under way in a shared directory. Even with it, I would still run worktrees.
Plugins named swarm or orchestration mostly automate prompts and roles on top of Agent Teams. They add no locking of their own.
What I would take away
Isolation buys the safety. Ownership settles the rest. The message is only how the other session finds out.
Anthropic's page on cross-session messaging is worth reading in full: https://code.claude.com/docs/en/cross-session-messaging
Top comments (0)