Feature Request: Enable Agent-to-Agent Communication for Collaborative Workflows

Status Closed — not planned

Maintainer reply None cached

Activity 9 comments · opened Aug 2, 2025 · closed Feb 6, 2026

Title: Feature Request: Enable Agent-to-Agent Communication for Collaborative Workflows

Is your feature request related to a problem? Please describe.

Yes. The current subagent architecture in Claude Code is excellent for delegation—handing off a self-contained task to a specialist and getting a result. However, it falls short for tasks that require true collaboration and iterative feedback between agents. This creates two primary problems:

Lack of Iterative Feedback Loops: Complex software development is rarely a linear process. For example, a common workflow is a dev-test-fix cycle. Currently, if I have a "Developer Agent" and a "Tester Agent," the workflow is cumbersome:

The Developer Agent writes code.
The user (me) must manually instruct the Tester Agent to test it.
If tests fail, the Tester Agent reports back to me.
I then have to copy the failure details, re-engage the Developer Agent, and provide the context for the fix.

This manual intervention breaks the autonomy of the system and makes it impossible to assign a high-level goal like "Implement and test feature X until it passes all acceptance criteria."

Destructive Interference in Parallel Work: When tackling a large epic, the natural approach is to use multiple agents in parallel. However, these agents are unaware of each other's existence or work-in-progress.

Scenario: I assign Agent A to build an API endpoint and Agent B to build a related frontend component. Both are working in the same codebase.
Agent A adds api/new-endpoint.ts.
Agent B, when attempting to build or test its own work, sees api/new-endpoint.ts as an unexpected file not relevant to its immediate task.
To "fix" its local build environment, Agent B might decide to run rm api/new-endpoint.ts, destroying Agent A's work.

This forces users into complex workarounds like Git Worktrees, which provide isolation but prevent true collaboration on a shared context.

In short, agents currently operate as isolated contractors. We need them to operate as a cohesive, communicative team.

Describe the solution you'd like

I propose introducing a first-class system for agent-to-agent communication. This could be implemented in layers, from a simple messaging API to a more advanced collaborative framework.

Level 1: A Core Messaging Bus
An internal API that allows a running agent (or subagent) to send a message to another named agent.

API: A new tool or internal function like sendMessage(targetAgent: string, message: object).
Example: A tester-agent could execute sendMessage('developer-agent-1', { type: 'TEST_FAILURE', file: 'auth.ts', line: 42, error: 'NullPointerException' }).
The developer-agent-1 would receive this message in its context and could be prompted to act on it.

Level 2: A Shared Dynamic State (or "Whiteboard")
A transient, shared key-value store or context space that is accessible to all agents within a single "team" or session. This would solve the parallel work problem.

How it works: Agents could post their status or discoveries to the whiteboard.
Example:
Agent A: sharedState.add('files_in_progress', 'api/new-endpoint.ts')
Agent B: const inProgress = sharedState.get('files_in_progress'); Before cleaning up its directory, Agent B would know to ignore files that other agents are actively working on.

Level 3: A "Team" or "Squad" Abstraction
A higher-level construct to formalize agent groups. When initiating a task, a user could assign it to a pre-configured team of agents.

Configuration: A user could define a frontend-team consisting of a react-developer agent, a css-stylist agent, and a cypress-tester agent.
Invocation: claude --team=frontend-team "Build a new settings page with these form fields."
The team would then autonomously coordinate using the messaging bus and shared state to complete the task.

Describe alternatives you've considered

I am aware of and have used the following workarounds, which highlights the need for a native solution:

Manual User Orchestration: As described above, the user acts as the communication bus. This is slow, error-prone, and doesn't scale.

File-Based Mailboxes: Having agents write status updates or messages to a shared communication.md file. This is clunky, requires agents to constantly poll the file, and is subject to race conditions.

Git Worktrees: This is the best current solution for preventing destructive interference in parallel work. It provides isolation. However, it does not enable collaboration. The agents remain unaware of each other.

Claude Code SDK: It is technically possible to build a custom orchestration script using the SDK that manages multiple agent processes and pipes I/O between them. This is extremely powerful but requires the user to become an expert in building agentic systems, which defeats the purpose of having a seamless, out-of-the-box tool. The proposed feature is about bringing this advanced capability into the core product for all users.

Additional context

Implementing this feature would be a transformative step for Claude Code, evolving it from a world-class "AI pair programmer" into a true "AI software development team in a box." It would unlock the ability to tackle much larger, more complex, and long-running tasks with a higher degree of autonomy.

Imagine being able to give Claude Code a JIRA epic and have a team of agents autonomously design the architecture, divide the work, implement features in parallel, test each other's code, and finally merge a complete, working feature branch. This is the future of agentic software development, and direct agent communication is the foundational technology required to get there.

Thank you for considering this. Your work on subagents has already laid an amazing foundation, and I believe this is the logical and most impactful next step.

View original on GitHub ↗

9 Comments

github-actions[bot] · 1 year ago

Found 3 possible duplicate issues:

If your issue is a duplicate, please close it and 👍 the existing issue instead.

🤖 Generated with Claude Code

mapedersen · 1 year ago

Would love this as well 💯👍

github-actions[bot] · 8 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

dpark2025 · 8 months ago

+10000

toolate28 · 8 months ago

Alternative Approach: Temporal Coordination via Shared Context Files

This is a thoughtful proposal. The use cases you describe—dev-test-fix cycles, parallel work interference—are real pain points I've encountered extensively.

I've been working on an approach that addresses these without requiring new messaging primitives. The key insight:

Real-time coordination assumes both agents run simultaneously. Most coordination problems are actually temporal—Agent A completes, Agent B continues later.

---

Mental Model Comparison

┌─────────────────────────────────────────────────────────────────────────┐
│                    REAL-TIME MESSAGING (Proposed)                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│    Agent A ◄─────────► [Message Bus] ◄─────────► Agent B               │
│       │                     │                        │                  │
│       │    ┌────────────────┴────────────────┐      │                  │
│       │    │  • Both must run simultaneously │      │                  │
│       │    │  • Shared memory required       │      │                  │
│       │    │  • Race conditions possible     │      │                  │
│       │    │  • State lost on termination    │      │                  │
│       │    └─────────────────────────────────┘      │                  │
│       ▼                                             ▼                  │
│   [Working]                                    [Working]               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                 TEMPORAL COORDINATION (Proposed Alternative)            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   Agent A                    .claude/                     Agent B       │
│      │                          │                            │         │
│      │    ┌─────────────────────┴─────────────────────┐     │         │
│      │    │  ORIENTATION.md  │  CONTEXT.md  │  state.json   │         │
│      │    └─────────────────────┬─────────────────────┘     │         │
│      │                          │                            │         │
│      ▼                          │                            │         │
│   [Writes] ────────────────────►│                            │         │
│      │                          │                            │         │
│   [Terminates]                  │  ~~~~ time passes ~~~~     │         │
│                                 │                            │         │
│                                 │◄──────────────────── [Reads]         │
│                                 │                            │         │
│                                 │                     [Continues]      │
│                                 │                            ▼         │
│                                 │                       [Writes]       │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐  │
│   │  • Agents can be separated by hours/days                        │  │
│   │  • Requires only filesystem                                     │  │
│   │  • Sequential by design (no race conditions)                    │  │
│   │  • State persists indefinitely                                  │  │
│   │  • Knowledge accumulates across sessions                        │  │
│   └─────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

---

Proposed: `.claude/` Directory Standard

.claude/
├── ORIENTATION.md      # Shared team understanding (your Level 3)
├── CONTEXT.md          # Accumulated state + handoff (your Levels 1 & 2)  
├── state.json          # Machine-readable session metadata
└── hooks/
    ├── on-init         # Load context at startup
    └── on-exit         # Preserve state before shutdown

Mapping to Your Proposal

┌────────────────────────────────────────────────────────────────────────┐
│                         FEATURE MAPPING                                │
├────────────────────────┬───────────────────────────────────────────────┤
│  Your Proposal         │  .claude/ Implementation                      │
├────────────────────────┼───────────────────────────────────────────────┤
│                        │                                               │
│  Level 1:              │  CONTEXT.md                                   │
│  Messaging Bus         │  "For Next Agent" section with structured     │
│                        │  handoff instructions                         │
│                        │                                               │
├────────────────────────┼───────────────────────────────────────────────┤
│                        │                                               │
│  Level 2:              │  CONTEXT.md + state.json                      │
│  Shared Whiteboard     │  Accumulates discoveries, tracks files        │
│                        │  in progress, persists across sessions        │
│                        │                                               │
├────────────────────────┼───────────────────────────────────────────────┤
│                        │                                               │
│  Level 3:              │  ORIENTATION.md                               │
│  Team Abstraction      │  Shared understanding of project shape,       │
│                        │  conventions, constraints. All agents         │
│                        │  read same orientation on startup.            │
│                        │                                               │
└────────────────────────┴───────────────────────────────────────────────┘

---

Your Use Cases, Solved

Use Case 1: Dev-Test-Fix Cycle

The Problem:

Developer Agent writes code
        ↓
User manually instructs Tester Agent  ◄── friction
        ↓
Tester reports to user                ◄── friction  
        ↓
User re-engages Developer             ◄── friction
        ↓
User provides context for fix         ◄── friction

The Solution:

# CONTEXT.md

## Current State
**Phase:** Testing
**Last action:** Developer Agent committed auth.ts refactor
**Branch:** feature/auth-jwt

## For Next Agent

If you are **Tester Agent**:
1. Run test suite against src/auth.ts
2. Update "Test Results" section below
3. If failures: describe issue and suggested fix
4. Update phase to "Fixing" if failures found

If you are **Developer Agent**:
1. Check "Test Results" section
2. Address any failures listed
3. Update "Last action" when complete
4. Set phase back to "Testing"

## Test Results
**Last run:** 2025-01-15T14:30:00Z
**Status:** FAIL

| Test | Result | Details |
|------|--------|---------|
| auth.test.ts:42 | ❌ FAIL | NullPointerException |
| auth.test.ts:67 | ✅ PASS | - |
| auth.test.ts:89 | ✅ PASS | - |

**Suggested fix:** Check for undefined user object before accessing .id property (line 38)

## Cycle History
1. Dev: Initial implementation
2. Test: 3 failures found  
3. Dev: Fixed null checks
4. Test: 1 failure remaining ◄── current

Result:

Developer Agent writes code
        ↓
[Writes CONTEXT.md, terminates]
        ↓
Tester Agent reads CONTEXT.md         ◄── automatic
        ↓
[Runs tests, writes results, terminates]
        ↓
Developer Agent reads CONTEXT.md      ◄── automatic
        ↓
[Fixes based on documented failures]

No user orchestration required. Agents coordinate through the file.

---

Use Case 2: Destructive Interference

The Problem:

Agent A: adds api/new-endpoint.ts
Agent B: sees unexpected file
Agent B: rm api/new-endpoint.ts      ◄── destroys Agent A's work

The Solution:

# CONTEXT.md

## Files In Progress (DO NOT MODIFY)

| File | Owner | Branch | Status |
|------|-------|--------|--------|
| api/new-endpoint.ts | Agent A | feature/api | Active |
| components/Settings.tsx | Agent B | feature/frontend | Active |
| utils/validation.ts | Agent A | feature/api | Complete |

## Shared Constraints

Before ANY of these operations, check the table above:
- `rm` / `del` - Do not delete files owned by other agents
- Refactoring - Do not move files owned by other agents
- Large reformats - Coordinate via CONTEXT.md first

## Cleanup Protocol

If you need to clean your working directory:
1. Read "Files In Progress" table
2. Only delete files not listed OR where you are Owner
3. If uncertain, add a note to "Coordination Needed" section

## Coordination Needed
(Agents add notes here when they need to modify shared resources)

- [Empty]

Result:

Agent A: adds api/new-endpoint.ts
Agent A: registers in CONTEXT.md "Files In Progress"
Agent A: [terminates]
        ↓
Agent B: [starts]
Agent B: reads CONTEXT.md
Agent B: sees api/new-endpoint.ts is owned by Agent A
Agent B: leaves file alone

---

What This Enables Beyond Your Proposal

Cross-Session Learning

# CONTEXT.md

## Discoveries (accumulated across sessions)

### Session 1 - 2025-01-10
- Auth module is sensitive to import order
- Must import passport before express-session

### Session 2 - 2025-01-11  
- Database connection requires 3s warmup in test environment
- Added retry logic to connection helper

### Session 3 - 2025-01-12
- Test suite flaky on Tuesdays due to cron job interference
- Disabled cron in test environment

### Session 4 - 2025-01-13
- CSS modules break if imported before React in test files
- Established import order convention in ORIENTATION.md

### Session 5 - 2025-01-14 (current)
- [This session will add discoveries here]

Each agent inherits everything previous agents learned. The "team" gets smarter over time without any orchestration layer.

---

Verification Checkpoints (SAIF Pattern)

# CONTEXT.md

## SAIF Phase Gate

**Current Phase:** 2 (Execute)
**Phase entered:** 2025-01-15T14:00:00Z

### Phase 2 → Phase 3 Requirements
Before any agent can move to Phase 3 (Verify), ALL must be true:

- [ ] All TypeScript compilation passes
- [ ] All unit tests pass  
- [ ] No ESLint errors
- [ ] CONTEXT.md updated with changes made
- [ ] Files In Progress table current

### If verification fails:

Do NOT proceed to Phase 3
Document blocker in "Blockers" section
Terminate cleanly
Next agent addresses blocker


### Blockers
(Agents document what prevented phase transition)

- [Empty]

Your proposal has agents messaging each other without verification. This model requires checkpoints before phase transitions.

---

Audit Trail

.claude/
└── logs/
    ├── access.jsonl        # What files each agent touched
    ├── proposed.jsonl      # What changes were proposed
    ├── applied.jsonl       # What was actually applied
    └── reasoning.jsonl     # Why decisions were made

Sample Log Entries:

// access.jsonl
{"ts":"2025-01-15T14:30:00Z","agent":"dev-1","file":"src/auth.ts","action":"read"}
{"ts":"2025-01-15T14:30:05Z","agent":"dev-1","file":"src/auth.ts","action":"write"}
{"ts":"2025-01-15T14:35:00Z","agent":"test-1","file":"src/auth.ts","action":"read"}

// proposed.jsonl
{"ts":"2025-01-15T14:30:05Z","agent":"dev-1","file":"src/auth.ts","diff":"+  if (!user) return null;"}

// reasoning.jsonl  
{"ts":"2025-01-15T14:30:05Z","agent":"dev-1","reasoning":"Adding null check per test failure in CONTEXT.md"}

Full transparency on what each agent did and why.

---

Comparison Table

| Aspect | Real-time Messaging | Temporal Coordination |
|--------|--------------------|-----------------------|
| Agents must run simultaneously | ✅ Required | ❌ Not required |
| Infrastructure needed | Message bus, shared memory | Filesystem only |
| Race conditions | Possible | Impossible (sequential) |
| State persistence | Lost on termination | Persists indefinitely |
| Knowledge accumulation | Per-session only | Across all sessions |
| Verification gates | Not built-in | Native (SAIF pattern) |
| Audit trail | Requires additional infra | Native (logs/) |
| Complexity | High (orchestration layer) | Low (read/write files) |

---

Integration with Devcontainers

{
  "postStartCommand": "claude context load .claude/",
  "preStopCommand": "claude context save .claude/",
  "customizations": {
    "claude": {
      "orientationPath": ".claude/ORIENTATION.md",
      "contextPersistence": true,
      "gitHooks": {
        "postCheckout": "claude context reload",
        "postMerge": "claude context reload"
      }
    }
  }
}

Context loads automatically on container start. Saves automatically before shutdown. Reloads on branch changes so agents don't carry stale assumptions.

---

Shell Aliases for Zero Friction

# Load full context (2 characters)
alias cc='claude context load .claude/'

# Quick status check
alias ccs='cat .claude/CONTEXT.md | head -30'

# Save before switching tasks  
alias ccsave='claude context save .claude/'

---

Summary

Your proposal identifies real problems. This approach solves them with:

No new messaging primitives - filesystem only
Temporal coordination - agents don't need to run simultaneously
Accumulated knowledge - team gets smarter over time
Verification checkpoints - phase gates prevent premature handoffs
Full audit trail - transparency on what each agent did and why
Native devcontainer integration - lifecycle hooks handle load/save

Happy to discuss implementation details or share the full specification.

---

This approach is already working in production workflows.

Pranav-Srinivasan · 7 months ago

+1000

github-actions[bot] · 6 months ago

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

marcindulak · 6 months ago

I think the newly released https://code.claude.com/docs/en/agent-teams may be close to the original idea.

Nevertheless, this issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.