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.