# Show HN: Async multi-agent coordination across physical environments

> Source: <https://github.com/BlahBlah23406/agent-comms>
> Published: 2026-09-15 15:40:45+00:00

A lightweight protocol and toolkit for AI coding agents to share context, hand off tasks across sessions, and collaborate in real-time across machines.

When working with AI coding agents (Claude Desktop, Antigravity, Cursor, etc.), two major challenges arise:

1. **Context Loss Across Sessions:** Starting a new chat or moving to another machine resets the agent's mental model and working memory.
2. **Multi-Agent Coordination:** Agents running in different environments or physical computers cannot easily communicate, exchange state, or run coordinated tasks.

**Agent Comms** provides a unified solution:

- **Context Capsules (Out-of-Session Handoff):** Packages an agent's task roadmap, architectural decisions, rejected hypotheses, and uncommitted git diffs into a compact, portable bundle. The next agent session resumes immediately without burning context tokens.
- **AHRP Live Relay (In-Session Collaboration):** A real-time WebSocket mesh supporting peer discovery, publish/subscribe messaging, and cross-machine Remote Procedure Calls (RPC).
- **Native MCP Integration:** Works out-of-the-box with Claude Desktop, Antigravity, and Cursor via the Model Context Protocol.

Agent Comms captures cognitive state alongside your working tree without polluting Git commit history:

- **State & Decisions:** Records what worked, what was rejected, and the immediate next steps.
- **Code Diffs:** Captures staged, unstaged, and untracked changes into a clean patch.
- **Briefing Generation:** Produces a token-efficient Markdown briefing tailored for the incoming agent.

```
Machine A (Active Session)                  Machine B (New Session)
 ┌──────────────────────────┐                ┌──────────────────────────┐
 │ Agent exports capsule    │──[File/Sync]──▶│ Agent imports capsule    │
 │ (diffs + state + roadmap)│                │ (restores diffs + state) │
 └──────────────────────────┘                └──────────────────────────┘
```

For multi-agent workflows, a lightweight relay server coordinates agents over WebSockets:

- **Peer Discovery:** Agents announce presence, roles, and hardware capabilities.
- **Cognitive Blackboard:** Replicated state where agents share real-time decisions and learnings.
- **Direct RPC:** Agents can invoke tools or run commands on peer machines.

**Using Pip:**

```
pip install git+https://github.com/BlahBlah23406/agent-comms.git
```

**Or Clone & Install Locally:**

```
git clone https://github.com/BlahBlah23406/agent-comms.git
cd agent-comms
pip install -e .
```

**One-Line Install Script:**

- **macOS / Linux:**

```
curl -sSL https://raw.githubusercontent.com/BlahBlah23406/agent-comms/master/install.sh | bash
```

- **Windows (PowerShell):**

```
irm https://raw.githubusercontent.com/BlahBlah23406/agent-comms/master/install.ps1 | iex
```

Run initial setup:

```
agent-comms setup
```

Before ending a session or switching computers:

```
agent-comms capsule pack \
  --task "AUTH-01" \
  --summary "Migrated auth module to JWT; integration test pending" \
  --next "Run pytest tests/test_auth.py" \
  --learning "finding:PyJWT requires algorithms=['HS256']"
```

Restore your uncommitted files and task briefing:

```
agent-comms capsule unpack "AUTH-01"
```

See two local agents discover each other and collaborate:

```
agent-comms demo
```

Agent Comms includes an MCP server exposing `export_handoff_capsule`, `import_handoff_capsule`, and `list_saved_capsules`.

Add to your MCP settings file:

```
{
  "mcpServers": {
    "agent-comms": {
      "command": "agent-comms",
      "args": ["mcp"]
    }
  }
}
```

Once added, interact naturally with your agent:

*"Save my progress into a handoff capsule for task AUTH-01."*

*"Resume task AUTH-01 from my latest capsule."*

- [**Natural Language User Guide** (`USER_GUIDE.md`)](https://github.com/BlahBlah23406/agent-comms/blob/master/USER_GUIDE.md) — Plain-English prompt examples for Claude Desktop, Antigravity, and Cursor.
- [**Onboarding Guide** (`ONBOARDING.md`)](https://github.com/BlahBlah23406/agent-comms/blob/master/ONBOARDING.md) — Step-by-step developer onboarding and distributed agent recipes.
- [**Protocol Specification** (`SPECIFICATION.md`)](https://github.com/BlahBlah23406/agent-comms/blob/master/SPECIFICATION.md) — Formal AHRP wire protocol and JSON schemas.
- [**Tutorial & Recipes** (`TUTORIAL.md`)](https://github.com/BlahBlah23406/agent-comms/blob/master/TUTORIAL.md) — Hands-on walkthroughs and implementation examples.