amq-bridge

Plug agents together across different sessions.

Concept

Pi session
  -> bridge
    -> transport
      -> shared mailbox

Codex session (coming soon)
  -> bridge
    -> transport
      -> shared mailbox

One shared mailbox. Any agent runtime can read and write. No central server. No cloud dependency.

Design

• transport behind an interface — swap the bus without touching agent logic
• behavior isolated from transport — inbox polling, reply tracking, attach/detach all live in the bridge core
• runtime adapter is thin — only resolves local identity and the mailbox root
• one bridge core, any agent — Pi, Codex, OpenCode all use the same code path
• pluggable transport — currently using agent-message-queue, but behind a thin transport layer so can be switched to other transports if needed.

Why

Agents are siloed. Each session is an island. If you run multiple agents — same machine, same task — they have no way to talk.

This bridge gives them a shared inbox. Send a message from one agent, pick it up from another. No HTTP polling. No REST API. No server to deploy.

Install into Pi

Prereqs:

# macOS
brew install avivsinai/tap/amq

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/avivsinai/agent-message-queue/main/scripts/install.sh | bash

Verify:

amq --version

pi install npm:agent-message-bridge

Then in Pi:

1. trust project if prompted

2. /reload

3. attach each session — every session must register its own name and the peer it talks to:

   Session Alice:

   /agent-bridge attach bob alice
   

   (args: <peer> [self] — self defaults to session name if omitted)

   Session Bob:

   /agent-bridge attach alice bob
   

4. send — either session can now send:

   /agent-bridge send hi from alice
   

5. inbox — check what arrived:

   /agent-bridge inbox
   

6. reply — reply to a specific message:

   /agent-bridge reply <msg-id> got it
   

Tools, not just commands

The bridge registers tools directly into the agent's toolset. That means the agent can use them autonomously — you don't need to type slash commands.

Tool	What it does
amq_bridge_send	Send AMQ message to attached peer
amq_bridge_reply	Reply to latest AMQ inbox message
amq_bridge_inbox	Inspect current AMQ inbox buffer
amq_bridge_status	Show current AMQ Bridge identity, peers, and root

Example flow — one prompt, no manual steps:

You: "Invite bob to play tic-tac-toe"

Session Alice (agent uses tools automatically):

1. Sees amq_bridge_send tool — sends bob a game invite
2. Auto-inbox polling picks up bob's reply
3. Reads it with amq_bridge_inbox
4. Replies with amq_bridge_reply — all autonomous

Session Bob (agent reacts to incoming message):

1. Auto-inbox loop picks up alice's invite
2. Bob's agent sees the message, decides to respond
3. Sends "let's play" back via amq_bridge_reply
4. Game on

The agent discovers peers, routes replies, and manages the conversation — you just say what you want.

Commands

Command	What it does
/agent-bridge attach <peer> [self]	Join the bus; self defaults to session name
/agent-bridge detach	Leave the bus
/agent-bridge send [--to peer] <msg>	Send message to primary peer (or --to)
/agent-bridge inbox	Read unread messages
/agent-bridge reply <msg-id> <msg>	Reply to a specific message
/agent-bridge status	Show identity, peers, mailbox root
/agent-bridge discover	List available AMQ agents on the bus
/agent-bridge connect	Pick an available agent and add as peer
/agent-bridge peers	Show connected peers
/agent-bridge peer add <handle>	Add a peer to the roster
/agent-bridge peer remove <handle>	Remove a peer
/agent-bridge peer primary <handle>	Set default send target
/agent-bridge help	Show usage info

Mailbox root

Default root is ~/.amq-bridge/mail, not the current directory. Two agents can communicate even from different folders.

Override:

PI_AMQ_ROOT=/path/to/shared/mail pi

Or project-local config .pi/amq-bridge.json:

{ "root": ".agent-mail" }

Auto inbox polling

When attached, the bridge polls the shared mailbox and injects unread messages into the agent session. The agent reacts without manual polling.

Transport

Default transport is AMQ — a zero-config message queue that uses the filesystem. No daemon, no ports, no infra.

---

See docs/roadmap.md for planned features, protocol design, and milestones.