claude-code - 💡(How to fix) Fix [FEATURE] multi-agent IPC

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• 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.

2. 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.

3. 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.

4. 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.

2. 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.

3. 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.).

4. 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.

5. 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.

6. 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

7. 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.