[FEATURE] multi-agent IPC

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I regularly run two (or more) Claude Code sessions on the same repo in
parallel — typically one per git worktree — to work on independent features
at the same time. For example, today I had Session A building a WhatsApp
admin chat UI on one branch, and Session B doing dashboard UI fixes on
another branch. Both sessions touched related files (the admin sidebar, a
shared Tailwind component, a few shared types).

The problem: the two sessions are completely isolated from each other.
Neither knows the other exists. So I (the human) end up being the only
communication channel between them — relaying "Session A just added a new
nav item, account for it in your sidebar restyle", or "Session B renamed
this prop, your code is now stale". This produces:

• Duplicate exploration ("which files does X live in?" — each session has to

re-discover the same things)

• Merge conflicts I have to resolve manually because both sessions edited

the same file without knowing

• One session silently undoing or contradicting work the other just did
• Wasted tokens and time re-narrating context to each session whenever they

need to know what the other is doing

• Lots of "wait, do that in the other window" copy-paste from me

The two sessions aren't competing — they're collaborating, and we just don't
have a primitive that lets them coordinate.

Proposed Solution

Some way for Claude Code sessions on the same repo (or org/project) to know
about and optionally communicate with each other. A few possible shapes,
ranked by complexity:

1. PASSIVE AWARENESS (lowest effort, high value)

Each session can see a list of other live sessions in the same repo and
what they're currently working on (current branch, current task summary,
files recently touched in the last N minutes). Something like:
/sessions
→ Session A — branch feat/admin-whatsapp, last touched
src/pages/admin/WhatsAppTab.jsx 2m ago, current task:
"adding reply-to-message feature"
→ Session B — branch ui/fixes, last touched
src/components/ui/table.jsx 30s ago, current task:
"table responsive tweaks"
Just knowing "another session is in this repo" + "their current focus"
removes 80% of the conflict pain.

1. SHARED NOTES / SCRATCHPAD

A repo-scoped append-only feed that any session can post to and any
session can read. E.g. /note added a new sidebar nav item, please
account for it. The other session sees it on its next tool call.
Basically a global TODO/heads-up board.

1. ACTIVE MESSAGING

/message session-b "are you done with table.jsx yet?" — directly send
a message that the other session sees as an interrupt/reminder on its
next turn. Could be opt-in per session.

1. SHARED MEMORY / FILE LOCKS

Optional advisory lock — "I'm about to edit src/components/Sidebar.jsx"
— so the other session gets a warning if it tries to edit the same file.

Any one of these would dramatically reduce the "human as message broker"
burden when running parallel sessions. #1 alone would already make me a lot
more comfortable spinning up two or three sessions on a single repo.

Alternative Solutions

What I currently do as workarounds:

• HUMAN AS BROKER: I'm the message bus. I copy/paste status between

windows ("the other session just renamed X to Y", "this file is being
worked on, hold off"). Works but is exhausting and error-prone — I'm
literally context-switching for the agents.

• SHARED NOTES FILE: I sometimes have each session write to a

.claude/coordination.md file at the repo root. The agents can both
read it. Works in principle but neither session knows when to check
it, so updates are stale by the time the other reads them.

• COMMIT-AS-MESSAGE: Use frequent commits as a coordination channel —

each session pulls the other's commits and reads the messages. Heavy
weight, only works for "done" work, useless for "I'm about to touch X".

• COMBINE INTO ONE SESSION: Give up on parallel and run everything in

a single session sequentially. Loses the whole point of parallel work
on a multi-feature day.

Other tools — Cursor, Codeium, etc. — don't really solve this either
because they're single-agent-per-window too. Tmux/multiplexers solve
the terminal layout problem but the agents are still siloed.

Priority recommendation: Medium — this is real friction for power users who run
parallel sessions, but it's a quality-of-life improvement, not a blocker. Saying
"Critical - Blocking my work" would overstate it (Anthropic gets a lot of
"Critical" requests and learns to discount them). Pick Medium or High if you do
this often.

Feature Category: "CLI commands and flags" doesn't quite fit. If there are
options like:

• "Session management"
• "Multi-agent / multi-instance"
• "Workflow / collaboration"
• "Other"

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

Real scenario from today (literally what prompted this issue):

1. I needed to ship two unrelated things to the same repo at the same time:

(a) a WhatsApp admin chat dashboard (lots of frontend + backend work),
and (b) UI polish to the admin sidebar/dialogs/for-stores page.

1. I created a git worktree at .worktrees/ui-fixes on branch ui/fixes, and

launched Session B (Claude Code) there for the UI work. My main checkout
stayed on a feature branch where Session A worked on WhatsApp.

1. Both sessions started editing the same parent file:

src/pages/AdminDashboard.jsx.
Session A needed to add a "WhatsApp" item to the sidebar sections array.
Session B was simultaneously restyling that same sidebar (dark theme,
RTL-aware alignment, etc.).

1. Neither session knew about the other. Session A added the WhatsApp tab

on its branch. Session B pushed its dark-sidebar work to main an hour
later, unaware. When I later merged Session A's branch to main, git
auto-merged successfully BUT only because the changes were spatially
non-conflicting. If they'd touched the same lines I'd have had a manual
resolution mid-merge.

1. Meanwhile I was personally Slacking between the two windows: "Session A

is adding a 'whatsapp' section, make sure your sidebar restyle keeps it",
"Session B renamed getLabel to t[], your code is out of date",
etc. This took real cognitive effort, slowed me down, and forced me to
keep both sessions' context in my own head.

1. WITH MULTI-AGENT IPC (even just option 1 from the proposed solution):

• Session A would see "Session B is currently editing AdminDashboard.jsx"

before opening it for write

• Session A could `/note "added 'whatsapp' to sections array, please

keep when restyling"` and Session B would see that on its next turn

• Session B finishing a refactor could broadcast "renamed getLabel

to t[]" so Session A picks it up

1. End result: I'd be spending zero brain cycles routing between them.

Both sessions would coordinate directly. I'd be the product owner,
not the message bus.

This is a recurring scenario — basically every multi-feature day where
I want to parallelize.

Additional Context

A few notes on implementation surface area:

• Discovery only needs to be repo-scoped. Sessions in different repos don't

need to see each other. Easy primitive: every session writes a small
heartbeat file under .claude/sessions/{sessionId}.json with branch +
current task summary + last-touched-files; other sessions read the
directory on demand. Filesystem coordination — no daemon required.

• Should be OPT-IN. Single-session purists shouldn't have ambient peer

awareness foisted on them. A setting like coordination: enabled or
a flag --peer-aware on launch.

• Could naturally integrate with git worktrees, since worktrees are the

canonical way to run parallel sessions today. git worktree list
already exists — Claude Code could enrich each entry with "Claude
session active here, current task: ...".

• For active messaging (option 3 in the solution), the receiving session

shouldn't be interrupted mid-tool-call. Messages should be queued and
surfaced at the next user-facing turn boundary.

• Privacy: only metadata that the user/operator explicitly chose to expose

(current task summary they typed, files they edited) — no automatic
conversation transcript sharing.

• This is not a replacement for proper git workflows (still need branches,

commits, etc.) — it's a layer on TOP that reduces the "human as router"
friction during active parallel work.

This conversation with Claude that generated the writeup was itself an
instance of the problem — I had to manually update both my sessions all
day. Meta enough.