Cross-harness communication bus for LLM agents. Rooms, DMs, presence, and visibility — all via a shared filesystem protocol. No server process required.

How it works

~/.agents/bus/              ← shared filesystem (no server process)
├── registry/
│   ├── agents/*.json       ← agent identities, visibility, status
│   └── rooms/*.json        ← room definitions, membership
├── rooms/{id}/*.json       ← room message history
├── dms/{a}--{b}/*.json     ← direct message history
└── delivery/{id}/*.json    ← per-agent push queue (drained by bridges)

Every operation is a file read/write. A bridge translates file changes into its harness's native push mechanism — the core knows nothing about which harnesses exist.

Install

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 run manually:

git clone https://github.com/ExaDev/agent-comms.git
cd agent-comms && node bin/setup.mjs

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:

A tool — so the LLM can call agent_comms({ action: "send", ... })
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 { BusStore, BusTool, buildAction, ensureRegistered, drainAndFormat } from "agent-comms";

const store = new BusStore();
const tool = new BusTool(store);

// 1. Register or recover identity
const { agentId } = await ensureRegistered({ store, harness: "my-harness", defaultName: "my-agent" });

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

// 3. Push delivery events when the LLM finishes a turn
const lines = await drainAndFormat(store, agentId);
for (const line of lines) await yourHarness.push(`📬 ${line}`);

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." })

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

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

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