# Agent Comms

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

Agent Comms is an open-source Python library and CLI toolkit that solves two core problems for AI coding agent workflows: context loss between sessions and multi-agent coordination across machines. It is hosted on GitHub under the username BlahBlah23406 and is installable via pip or a one-line shell script. The project targets developers working with AI coding agents such as Claude Desktop, Antigravity, and Cursor.

## What It Is

Agent Comms provides a unified protocol for AI coding agents to preserve and transfer cognitive state between sessions and to communicate in real time across different machines. It combines two complementary mechanisms: **Context Capsules** for out-of-session handoff and the **AHRP Live Relay** for in-session multi-agent collaboration. The project also ships a native MCP (Model Context Protocol) server, making it directly usable from Claude Desktop, Antigravity, and Cursor without additional glue code.

## Context Capsules: Out-of-Session Handoff

Context Capsules are the core artifact for preserving an agent's working state across session boundaries. When a developer ends a session or switches machines, the agent packages:

- **Task roadmap and architectural decisions** — what was tried, what was rejected, and what comes next
- **Code diffs** — staged, unstaged, and untracked changes captured as a clean patch, without polluting Git commit history
- **Token-efficient Markdown briefing** — generated for the incoming agent to resume immediately

On the receiving machine, `agent-comms capsule unpack` restores uncommitted files and the full task briefing, allowing the next agent session to pick up exactly where the previous one left off.

## AHRP Live Relay: Real-Time Multi-Agent Collaboration

For workflows where multiple agents run simultaneously across different environments or physical computers, Agent Comms provides a WebSocket mesh relay server implementing the AHRP (Agent Handoff Relay Protocol) wire protocol. Key capabilities include:

- **Peer discovery** — agents announce presence, roles, and hardware capabilities
- **Publish/subscribe messaging** — agents broadcast and receive topic-scoped messages
- **Cognitive Blackboard** — replicated shared state for real-time decision and learning exchange
- **Direct RPC** — agents can invoke tools or run commands on peer machines

The formal AHRP wire protocol and JSON schemas are documented in a `SPECIFICATION.md` file in the repository.

## MCP Integration and Supported Agents

Agent Comms ships a built-in MCP server that exposes three tools: `export_handoff_capsule`, `import_handoff_capsule`, and `list_saved_capsules`. Adding a single JSON block to an MCP settings file connects any compatible agent. The README explicitly lists Claude Desktop, Antigravity, and Cursor as supported hosts, and the repository includes a `USER_GUIDE.md` with plain-English prompt examples for each.

## Setup and Installation

The project supports multiple installation paths:

- `pip install git+https://github.com/BlahBlah23406/agent-comms.git`
- Clone and `pip install -e .` for local development
- One-line curl/PowerShell install scripts for macOS, Linux, and Windows

After installation, `agent-comms setup` runs initial configuration. A built-in `agent-comms demo` command launches a local two-agent collaboration scenario for immediate exploration.

## Current Status

The repository was created in September 2026 and last pushed on September 15, 2026, indicating very early-stage activity. It carries 1 star and 0 forks at the time of indexing. The README references passing tests and Python 3.9+ compatibility. The repository README lists an MIT badge, though the GitHub About section notes "No license specified" — the license status should be verified before production use. Documentation includes a User Guide, Onboarding Guide, Protocol Specification, and Tutorial.

## Features
- Context Capsules for out-of-session agent handoff
- AHRP Live Relay WebSocket mesh for real-time multi-agent collaboration
- Native MCP server integration (Claude Desktop, Antigravity, Cursor)
- Captures staged, unstaged, and untracked git diffs without polluting commit history
- Token-efficient Markdown briefing generation for incoming agents
- Peer discovery with role and hardware capability announcements
- Cognitive Blackboard for shared real-time agent state
- Cross-machine Remote Procedure Calls (RPC) between agents
- Publish/subscribe messaging across agents
- CLI with capsule pack/unpack, demo, setup, and mcp commands
- One-line install scripts for macOS, Linux, and Windows
- Python 3.9+ support

## Integrations
Claude Desktop, Antigravity, Cursor, Model Context Protocol (MCP), Git, WebSockets

## Platforms
CLI, API, WINDOWS, MACOS, LINUX

## Pricing
Open Source

## Links
- Website: https://github.com/BlahBlah23406/agent-comms
- Documentation: https://github.com/BlahBlah23406/agent-comms/blob/master/USER_GUIDE.md
- Repository: https://github.com/BlahBlah23406/agent-comms
- EveryDev.ai: https://www.everydev.ai/tools/agent-comms