agent-communication-bridge

Local Model Context Protocol (MCP) server, registry, and client hooks for messaging between Antigravity (agy), OpenAI Codex (codex), and OpenCode (opencode) sessions on the same machine.

How it works

• Registry (http://localhost:4999): An Express + WebSocket + SQLite server that tracks active sessions, stores messages, and records delivery states (queued, delivered_to_bridge, displayed_to_client, answered, failed).

• MCP server (acb mcp start): Exposes messaging tools inside each client and resolves the active workspace path from the host or parent process so separate projects do not collide on a plugin directory.

• Session isolation: Each live session gets a unique agentId (client-<type>-<projectHash>-<sessionTag>). Multiple windows or sessions in the same project stay separate without kicking each other off the WebSocket.

• Turn delivery: Antigravity hooks (SessionStart / Stop + Language Server), Codex app-server (codex >= 0.162 or acb codex app-bridge), and the OpenCode plugin start a turn in the receiving session when a message arrives.

Related MCP server: hauddy

Requirements

• Node.js >= 22

• pnpm

• At least one client installed: agy, codex, or opencode

Install

git clone https://github.com/Ezhil948/agent-communication-bridge.git
cd agent-communication-bridge
pnpm install
pnpm run build
npm install -g .

On macOS, Linux, or Git Bash you can run bash bin/install.sh instead.

This installs both agent-communication-bridge and acb on PATH.

Setup

Start the registry and configure the clients you use (one-time per machine):

acb up
acb antigravity install-plugin
acb init --client codex --yes
acb opencode install-plugin --global
acb doctor

For per-project configuration (writes .mcp.json and optionally scopes sessions with --identity), run acb init inside the project directory.

Usage

1. Open your project in two clients (or start a headless Codex worker with acb codex app-bridge --project "<path>").

2. From one session, call list_agents(includeClients=true) to find the target's agentId.

3. Call message_client_session(clientId, message, expectsResponse=true). Optionally pass model or reasoning to override them for that turn.

4. The receiving session wakes up, reads channel_inbox(pendingOnly=true) if needed, and answers via reply using replyWith.agentId, replyWith.conversationId, and replyWith.replyTo.

MCP tools

CLI

acb up                         # Start background registry on :4999
acb down                       # Stop background registry
acb status                     # Show registry status and agent count
acb list                       # List registered sessions
acb prune                      # Remove stale entries
acb doctor                     # Check Node, PATH, registry, and client plugins
acb init [--project <path>]    # Write .mcp.json and configure clients
acb antigravity <cmd>          # install-plugin | attach | hook-stop | hook-session-start
acb codex <cmd>                # start | app-bridge | tmux-bind | tmux-sidecar
acb opencode <cmd>             # start | bridge | install-plugin
acb prompt <cmd>               # path | show | init | edit | reset

Notes

• Separate windows, CLI processes, and projects run as isolated sessions. If one IDE window shares a single MCP child process across multiple tabs, those tabs share that client connection unless separated with --identity.

• See docs/architecture.md, docs/cli-reference.md, and CONTRIBUTING.md for details.

License

MIT