Claude Code cross-session messaging does not prevent concurrent file overwrites

What the messaging feature actually does

A developer writing on dev.to describes running two Claude Code sessions against the same repository and finding that the built-in coordination solves a narrower problem than expected. Claude Code ships with cross-session messaging: according to Anthropic's documentation, one session can notify another that a change broke something it depended on, or unblock a peer by answering a question. Two tools support this — ListAgents, to see which sessions are reachable, and SendMessage, to address one by name. The /list-agents command (also spelled /peers) shows what a session can contact. Nothing has to be switched on, but there is a version floor: 2.1.224 or later on macOS, Linux and WSL 2, and 2.1.234 or later on native Windows. Older builds do not recognise the command at all.

Coordination is not a lock

The key limitation, per the same documentation, is that a message is only text one Claude writes to another — never the sender's conversation history or files. Two sessions can therefore be perfectly well informed about each other and still both be about to write the same schema.ts in the same folder. Anthropic states this directly: 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 reconciling the writes. Messaging tells the other session what happened; it does not stop a write from landing.

Worktrees provide the isolation

The write-up's recommended protection is a git worktree per session. Running claude --worktree backend in one terminal and claude --worktree frontend in another gives each session its own directory, its own branch and its own copy of the tracked files. Per the docs, edits in one session then never touch files in another, and Claude Code refuses an edit aimed from inside a worktree back at the main checkout, so the boundary is enforced by the tool rather than left to convention. The author also recommends adding .claude/worktrees/ to .gitignore so worktree contents do not show up as untracked noise in the main checkout.

With isolation in place, messaging becomes useful in the way it was meant to be: session A commits an API change and sends session B the commit hash plus the list of files that moved; B rebases or cherry-picks and re-reads what changed. If both touched the same file, git raises a conflict — something that interrupts the developer and can be resolved — instead of a silent overwrite that surfaces later, if it surfaces at all.

Someone still has to own the shared files

Worktrees do not decide who owns package.. For files both sessions genuinely need to change, the author's advice is deliberately unexciting: a single owner per file at any moment, different files in parallel and the same file in sequence, written into the prompts as a protocol. Each session gets named directories it owns, a handoff must go through a message before either side touches a file the other holds, and a commit is required before that handoff.

Agent Teams and MCP Agent Mail fall short differently

The post also weighs the alternatives. Agent Teams, the experimental mode behind the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS flag, lets a lead session spawn and supervise teammates and provides a shared task list, a mailbox and direct messages; claiming a task is protected by a file lock. But that lock sits on the task record, not on source files — it coordinates who does what without preventing two writers from landing on one file, which is why splitting responsibility by file remains the official recommendation. MCP Agent Mail, a third-party effort, comes closest to addressing the gap: persistent agent identities, threaded inboxes and outboxes, file reservations by path and glob, TTLs on stale reservations, and an optional pre-commit or pre-push guard. It is the only option of the three that models file ownership at all, yet its reservations are advisory — the server reports a conflict rather than acting as a transactional write lock, and the guard can block a commit without stopping a write already under way in a shared directory. Plugins marketed as swarm or orchestration tools largely automate prompts and roles on top of Agent Teams and add no locking of their own.

Why it matters

Running several AI coding agents against one repository is becoming routine, and the failure mode described here is quiet rather than loud: a fully informed agent can still destroy a peer's work. The piece is a useful reminder that a communication channel is not a concurrency control. Until agent tooling ships real file-level locking, the dependable pattern is unglamorous — hard isolation through git worktrees, plus explicit, human-defined ownership rules for anything the sessions share.