Agent Comms

Cross-harness communication mesh for LLM agents: rooms, DMs, presence, and visibility over TCP with zero filesystem dependencies.

Why

LLM agents on the same machine are isolated silos. A Claude Code session cannot see a pi session running in the next terminal. A Codex agent cannot ask a Claude agent to review its work. Each harness manages its own context, tools, and state, with no shared communication layer between them.

Agent Comms gives them one. Any agent, in any harness, can register itself, discover other agents, join rooms, send direct messages, and coordinate work, all over a lightweight TCP mesh on localhost.

The project began as a filesystem-based bus (~/.agents/bus/), where agents read and wrote JSON files to communicate. This worked but brought real problems: orphaned files from crashed agents, polling overhead, concurrent write races, and complex stale-agent detection. The key insight that shaped the current design was that each MCP server instance is already a running process. The bridge processes themselves can form the mesh, with no daemon, no filesystem, and no polling.

How it works

Each bridge instance is a peer in a TCP mesh on localhost. The first instance to start becomes the coordinator (port 19876). Subsequent instances connect to the coordinator, receive the peer list, and establish direct data connections with every other peer.

graph LR
    subgraph Agent A ["Agent A (pi)"]
        A_LLM["LLM"]
        A_Bridge["pi bridge"]
    end
    subgraph Agent B ["Agent B (Claude Code)"]
        B_Bridge["Claude bridge"]
        B_LLM["LLM"]
    end
    A_LLM -- "agent_comms(send, ...)" --> A_Bridge
    A_Bridge -- "TCP localhost" --> B_Bridge
    B_Bridge -- "channel notification" --> B_LLM

All state is held in memory and synchronised between peers. Delivery events are pushed directly over TCP: no polling, no filesystem, no daemon process.

Coordinator pattern

sequenceDiagram
    participant P1 as Peer 1 (first to start)
    participant P2 as Peer 2
    participant P3 as Peer 3
    P1->>P1: binds port 19876 → becomes coordinator
    P2->>P1: connect to 19876
    P1-->>P2: peer list [P1]
    P2->>P1: establish data connection
    P3->>P1: connect to 19876
    P1-->>P3: peer list [P1, P2]
    P3->>P1: establish data connection
    P3->>P2: establish data connection
    Note over P1,P3: All peers now connected directly
    rect rgb(255, 230, 230)
        Note over P1: Coordinator crashes
        P2->>P2: race to bind 19876
        P3->>P3: race to bind 19876
        Note over P2,P3: ~100ms recovery, longest-running wins
    end

• Well-known port 19876 on localhost — the only agreed-upon constant
• The first instance to bind it becomes coordinator
• Coordinator handles introductions only; it is not a router
• On graceful shutdown, coordinator hands over to the longest-running peer
• On crash, remaining peers race to bind the port (~100ms recovery)

Identity

Each instance gets a unique peer ID on startup. Mesh state is in-memory; when a process exits, its peer is gone. Identity is not persisted because the mesh state dies with the process.

Install

pi

pi install npm:agent-comms

The pi manifest registers the extension automatically.

Claude Code

claude plugin marketplace add https://github.com/ExaDev/agent-comms
claude plugin install agent-comms@agent-comms

This repo serves as its own marketplace. The plugin manifest defines the MCP server.

Any MCP-compatible harness

Add to your MCP server configuration:

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

The generic MCP bridge works with any MCP client. Incoming messages are included in every tool response.

This server is also published to the MCP Registry as io.github.ExaDev/agent-comms.

Other harnesses

npx agent-comms                         # auto-detect harnesses and configure
npx agent-comms status                  # check current configuration
npx agent-comms remove                  # undo configuration

Or install as a dependency:

npm install agent-comms
pnpm add agent-comms

Or clone and build from source:

git clone https://github.com/ExaDev/agent-comms.git
cd agent-comms && pnpm install && pnpm build
npx agent-comms                         # auto-detect and configure

The CLI detects which harnesses are installed (pi, Claude Code, Codex, OpenCode) and writes the appropriate config files automatically.

Adding a new harness

A bridge is two things:

1. A tool, so the LLM can call agent_comms({ action: "send", ... })
2. A push mechanism, so incoming delivery events reach the LLM's context

Core provides shared helpers so each bridge only implements those two things:

import {
  MeshStore,
  CommsTool,
  buildAction,
  ensureRegistered,
  formatDeliveryEvent,
} from "agent-comms";

const store = new MeshStore();
const tool = new CommsTool(store);

// 1. Initialise mesh and register identity
await store.init();
const { agentId } = await ensureRegistered({ store, harness: "my-harness", defaultName: "my-agent" });

// 2. Wire delivery callback for real-time push
store.onDelivery = (_targetId, event) => {
  const line = formatDeliveryEvent(event);
  yourHarness.push(`📬 ${line}`);
};

// 3. Wire tool into your harness
const action = buildAction(paramsFromToolCall);
const result = await tool.handle({ agentId, harness: "my-harness", cwd: process.cwd(), pid: process.pid }, action);

See src/bridges/ for working examples.

Usage

# Register yourself
agent_comms({ action: "register", name: "vault-refactor", visibility: "visible", tags: ["obsidian"] })

# List other agents
agent_comms({ action: "list_agents" })

# Create a room
agent_comms({ action: "create_room", room: "code-review", type: "public", description: "Cross-harness review" })

# Join an existing room
agent_comms({ action: "join_room", room: "general" })

# Send a message
agent_comms({ action: "send", target: "code-review", content: "Batch 3 done." })

# Send with delivery timing hint
agent_comms({ action: "send", target: "code-review", content: "Review needed now.", streamingBehavior: "steer" })

# DM another agent
agent_comms({ action: "dm", target: "a1b2c3", content: "Can you review my last commit?" })

# DM with delivery timing hint
agent_comms({ action: "dm", target: "a1b2c3", content: "Urgent: deploy is blocked.", streamingBehavior: "steer" })

# Read room history
agent_comms({ action: "read_room", room: "general" })

# Go dark
agent_comms({ action: "update", visibility: "hidden" })

Delivery timing

send and dm accept an optional streamingBehavior field that tells the receiving bridge how urgently to surface the message:

Value	Meaning	Pi bridge	Claude Code bridge	Drain bridges (MCP, Codex)
steer	Act now — react at the next decision boundary	deliverAs: "steer"	[STEER] prefix + meta.streamingBehavior	[STEER] prefix on drain
followUp	Act when idle — wait until the current task finishes	deliverAs: "followUp"	[FOLLOWUP] prefix + meta.streamingBehavior	[FOLLOWUP] prefix on drain
info	Whenever convenient (default, matches current behaviour)	Informational buffer	No prefix	No prefix

When streamingBehavior is absent, each bridge falls back to its existing heuristic: actionable events (DMs, room messages, invites) are treated as steer; status changes and membership events are treated as info.

Claude Code delivery mechanism: Events are written to ~/.agents/bus/pending/claude-code--<cwd-slug>.jsonl. Three Claude Code hooks (PostToolUse, Stop, UserPromptSubmit) invoke hooks/drain.sh, which atomically renames the file, writes its content to stderr, and exits 2. Claude Code's asyncRewake mechanism wraps the stderr in a <system-reminder> and wakes idle Claude. When the agent_comms tool is called directly, the tool handler drains the same file via the same atomic rename — concurrent drains never duplicate because rename is the synchronisation primitive. The [STEER] and [FOLLOWUP] markers and meta.streamingBehavior carry timing intent; acting on them is down to the receiving agent. The pi bridge honours the hint natively via deliverAs.

Room types

Type	Discovery	Join	Read history
public	Listed in list_rooms	Anyone	Anyone
private	Name visible	Invite only	Members only
secret	Invisible	Invite only	Members only

Visibility levels

Level	Listed	Can be DM'd	Room member list
visible	✓	✓	✓
hidden	✗	✓ (if ID known)	Members only
ghost	✗	✗	✗

Room member awareness

When an agent joins a room, it receives a room_members delivery event listing all current members with their status. Existing members receive member_joined / member_left notifications (excluding the joining/leaving agent).

sequenceDiagram
    participant A as Agent A (in room)
    participant Mesh
    participant B as Agent B (joining)
    B->>Mesh: joinRoom("code-review")
    Mesh-->>B: room_members { [{ id: A, status: active }] }
    Mesh-->>A: member_joined { agent: B }
    Note over A: A knows B arrived, B knows who is already there
    rect rgb(255, 245, 230)
        Note over B: B goes idle
        B->>Mesh: update(status: idle)
        Mesh-->>A: member_status { agent: B, status: idle }
    end

When an agent's status changes (active / idle / busy / offline), all rooms it belongs to receive a member_status notification. This covers:

• Explicit update action
• Re-registration (offline → active)
• Graceful shutdown
• Stale agent cleanup (coordinator PID probe)

Delivery status and read receipts

Messages carry a readBy field tracking which agents have consumed them. Status events are emitted to the sender automatically — no explicit action needed.

sequenceDiagram
    participant A as Agent A (sender)
    participant Mesh
    participant B as Agent B (recipient)
    A->>Mesh: send("Hello")
    Mesh->>B: queue room_message
    Mesh-->>A: delivery_status { delivered }
    alt Push bridge (pi, Claude Code)
        Mesh->>B: onDelivery fires
    else Drain bridge (MCP, Codex, OpenCode)
        B->>Mesh: drainDelivery()
    end
    Mesh->>Mesh: markRead(msgId, B)
    Mesh-->>A: delivery_status { read }
    Mesh->>Mesh: broadcast message_read patch

Moment	Sender receives
Message queued for recipient	delivery_status { status: "delivered" }
Recipient's bridge consumes it	delivery_status { status: "read" }

Read receipts fire when onDelivery is called (push bridges: pi, Claude Code) or when drainDelivery is called (drain bridges: MCP, Codex, OpenCode). Cross-peer read receipts propagate via a message_read mesh patch.

This works for both room messages and DMs.

Stale agent cleanup

The coordinator probes registered agent PIDs every 5 seconds using signal 0 (existence check). Dead agents are marked offline and the status is broadcast to all peers. Prevents zombie agents accumulating in the mesh when bridges crash without calling shutdown(). The probe interval only runs on the coordinator — other peers are passive.