claude-code - 💡(How to fix) Fix [FEATURE] Native support for async git-based multi-agent coordination (scope enforcement, round management) [1 participants]

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

Claude Code has no native support for coordinating multiple agent sessions working on a shared codebase. Existing feature requests (#1770, #24798, #37993) focus on real-time inter-agent messaging (MCP channels, event buses, shared scratchpads). There is no support for asynchronous, git-based coordination — where correctness and auditability matter more than speed.

We built a working system using git branches as the communication bus, Redis for round signaling, tmux for session isolation, and CLAUDE.md for file-level scope enforcement. It works WITHOUT any Claude Code modifications — but three native primitives would eliminate the external dependencies and make the pattern first-class.

Before filing, we reviewed open issues (#1770, #24798, #37993, #45147, #28283, #28229, #44701) and confirmed this pattern is architecturally distinct — async git-based coordination vs real-time messaging. The architect agent conducted the duplicate review and recommended a new issue.

A working proof-of-concept exists: h-conductor (coordination) + h-context (context). The combined pattern tested in the audit that ships in production at h-cli (241 commits (public, more during build).

Proposed Solution

Three native features:

1. --scope <dir> flag (or CLAUDE.md directive)

Restrict an agent's file write access to a specific directory. Currently enforced via prompt instructions + architect review at merge time.

claude --scope expertdomain/   # agent can only write within this dir

Or via CLAUDE.md:

scope:
  write: ["expertdomain/", "experiments/x/"]
  read: ["*"]

2. Round signaling primitive

Replace external Redis dependency with a native mechanism for agents to signal task completion to a coordinator:

claude --signal-done           # agent signals completion
claude --wait-for team1 team2  # coordinator waits for N agents

3. Git-branch-aware task injection

Replace external conductor script with native branch-watching:

claude --watch-branch framework/round-5   # agent watches for branch, reads ANNOUNCEMENT.md

Alternative Solutions

The current system works without Claude Code changes, using:

• Git branches as the communication bus (architect writes ANNOUNCEMENT.md on a team branch, team replies with REPLY.md)
• Redis for round signaling (SADD when done, conductor auto-notifies)
• tmux for session isolation (one pane per agent)
• File-level scope enforcement via CLAUDE.md per team directory
• h-context description for structured persistent context across sessions. README-only; working implementation available on request
• h-conductor description for multi-agent coordination conductor (Redis round management, tmux session orchestration, auto-notification). README-only; working implementation available on request

This works but requires external infrastructure (Redis, conductor script) and relies on prompt-based scope enforcement rather than structural guarantees.

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

5 Claude Code instances collaborate on a security audit:

┌─────────────┐
│  Operator    │  (human — sets scope, makes decisions)
└──────┬──────┘
       │
┌──────▼──────┐
│  Architect   │  (Claude Code — coordinates, reviews, merges)
│  main branch │
└──┬──┬──┬──┬─┘
   │  │  │  │   ANNOUNCEMENT.md (on team branches)
   │  │  │  │   ◄── REPLY.md (team pushes back)
┌──▼┐┌▼┐┌▼┐┌▼──┐
│ FW ││PM││QA││INF│  (each: own Claude Code session, own tmux pane, own dir)
└────┘└──┘└──┘└───┘
   │  │  │  │
   └──┴──┴──┘──► Redis SADD round:done
                  Conductor notifies architect

Production results:

• 33 rounds, 5 teams, 255+ commits
• Self-correcting: caught premature reproducibility closure (3 rounds of refinement), measurement error (denominator correction), stale claims (pre-publication verification found 6 issues across 4 teams — all fixed before release)
• Multi-turn adversarial harness: adaptive attacker LLM driving 10-turn scenarios, evaluated across two judge-architecture arms
• Zero scope violations across 33 rounds

Additional Context

What makes this different from #1770 / #24798:

Those issues request real-time inter-agent messaging. This approach is deliberately asynchronous — git is the communication bus. This gives:

• Full auditability — every coordination message is a git commit
• Self-correcting workflow — negative results are undeniable because the git trail preserves them
• No infrastructure dependency — no MCP plugins, no custom servers, no notification routing
• Scope safety — agents cannot write outside their directory (enforced at merge time)

The trade-off is speed (async round-trip vs real-time). For audit/research/engineering work where correctness > speed, async wins.

Related:

• #1770 — parent-child monitoring (real-time, different pattern)
• #24798 — inter-session communication (real-time messaging, different pattern)
• #37993 — MCP notification routing (infrastructure-level, different layer)
• h-context description for structured persistent context across sessions. README-only; working implementation available on request
• h-conductor description for multi-agent coordination conductor (Redis round management, tmux session orchestration, auto-notification). README-only; working implementation available on request