Skip to main content
Glama

agent-bus-mcp 🚌

Universal Multi-Agent Communication Bus & Doorbell Wakeup System
Connect Claude Code, OpenAI Codex, Google Antigravity, and DeepSeek Harness (DSH) over standard Model Context Protocol (MCP) and SQLite.

License: MIT Python: 3.9+ MCP: 2024-11-05 Tests: Passing


🌟 Why agent-bus-mcp?

Modern AI agents often operate in isolated silos:

  • Claude Code runs in its own CLI or Chat UI;

  • Google Antigravity operates in terminal raw mode;

  • OpenAI Codex and DeepSeek Harness have separate runtimes.

Existing orchestration tools rely on fragile PTY keyboard simulation (frequently hanging on carriage returns), single-file overwrites, or lack autonomous push notification.

agent-bus-mcp solves this with a three-layer architecture:

  1. Universal Addressing & Identity: Every agent registers a unique ID (antigravity-lead, coordinator, deepseek-coder). Multiple instances never collide.

  2. Persistent Concurrency Engine: SQLite with Write-Ahead Logging (WAL), ACID transactions, status tracking (unread -> delivered -> read), and complete audit history.

  3. Heterogeneous Doorbell Subsystem: Delivers sub-second (0.7s) reactive wakeups to sleeping agents without requiring manual human keystrokes.


Related MCP server: mcp-comms

πŸ“ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    Heterogeneous Agents                     β”‚
β”‚    Antigravity    β”‚    Claude Code    β”‚   DeepSeek / Codex  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
               β”‚ (Standard MCP Tools or CLI)
               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚             agent-bus-mcp Server (JSON-RPC 2.0)             β”‚
β”‚   Tools: bus_send / bus_inbox / bus_history / bus_register  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ (ACID Transactions & Status Tracking)
                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚             SQLite WAL Database (~/.agent-bus/bus.db)       β”‚
β”‚  - messages: message_id, from, to, topic, status, timestampsβ”‚
β”‚  - agents: agent_id, framework, doorbell_type, last_seen    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                               β”‚ (Targeted Doorbell Wakeup)
                               β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     Doorbell Drivers                        β”‚
β”‚  - Antigravity Driver (Platform Reactive Task Wakeup)       β”‚
β”‚  - Claude Code Driver (API Chat Turn Injection)             β”‚
β”‚  - DSH / Unix Driver  (FIFO Named Pipe / Socket Signals)    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸš€ Quickstart

1. One-Click Installation

Clone and run the installer:

git clone https://github.com/tulong66/agent-bus-mcp.git
cd agent-bus-mcp
./install.sh

The installer automatically:

  • Sets up ~/.agent-bus/ and initializes the SQLite WAL database;

  • Installs the global agent-bus CLI to ~/.local/bin/agent-bus;

  • Auto-detects and injects MCP configuration into:

    • ~/.claude.json (Claude Code)

    • ~/.gemini/config/mcp_config.json (Antigravity)

    • ~/.codex/config.json (Codex)

    • ~/.dsh/ (DeepSeek Harness)

2. Verify Installation

agent-bus agents

Output:

AGENT ID                  FRAMEWORK       STATUS     DOORBELL TARGET
--------------------------------------------------------------------------------
antigravity-lead          antigravity     active     ~/.agent-bus/doorbells/antigravity-lead.bell
coordinator               claude-code     active     ~/.agent-bus/doorbells/coordinator.bell
deepseek-coder            dsh             active     ~/.agent-bus/doorbells/deepseek-coder.bell
codex-lead                codex           active     ~/.agent-bus/doorbells/codex-lead.bell

πŸ› οΈ MCP Tools Reference

When connected via MCP, any agent can call these standard tools:

Tool

Description

Key Arguments

bus_send

Send a message to an agent & ring its doorbell

to, content, topic, from_agent

bus_inbox

Fetch unread messages from SQLite

agent_name, unread_only, mark_read

bus_history

Query dialogue history between two agents

agent_a, agent_b, limit

bus_list_agents

List all active agents on the bus

(none)

bus_register

Register identity & doorbell configuration

agent_id, framework, doorbell_target


πŸ’» CLI Usage

Humans, background scripts, or agents using bash can interact via agent-bus:

# Send a message to an agent
agent-bus send --to coordinator --from antigravity-lead --topic review "Please inspect PR #12"

# View inbox for an agent
agent-bus inbox --agent coordinator

# View conversation history
agent-bus history antigravity-lead coordinator

# Block and listen for incoming doorbell
agent-bus listen --agent antigravity-lead --timeout 300

πŸ“š Guides for Specific Frameworks


πŸ§ͺ Testing

Install the test runner once, then run the suite:

uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest tests/ -v

πŸ“„ License

MIT License. Feel free to use in personal, academic, or commercial multi-agent systems.

Available Tools

6 tools
bus_historyA

Query chronological dialogue history between two agents from SQLite storage.

Inputs: agent_a (required), agent_b (required), limit.

bus_inboxA

Fetch incoming messages for a specific agent from the persistent SQLite inbox. Supports optional blocking wait.

Inputs: agent_name (required), wait, limit, timeout, +2 more.

bus_list_agentsA

List all active registered agents and their statuses on the universal communication bus.

Inputs: no named parameters.

bus_registerB

Register or update an agent's identity and doorbell configuration on the bus.

Inputs: agent_id (required), framework, doorbell_type, doorbell_target.

bus_sendA

Send a message to another agent on the universal agent bus. Persists to SQLite and triggers the recipient's doorbell for immediate wakeup.

Inputs: to (required), content (required), topic, from_agent, +1 more.

bus_wait_messageA

Long-poll and wait for an incoming message on the bus. Blocks until a message arrives or timeout expires. Eliminates terminal polling.

Inputs: agent_name (required), timeout, mark_read.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation3/5

    Most tools have clear, distinct purposes, but bus_inbox and bus_wait_message overlap heavily: both retrieve incoming messages and support blocking behavior. This creates potential confusion about which to use for waiting versus fetching.

    Naming Consistency3/5

    All tools share a consistent bus_ prefix, but the naming patterns after the prefix are mixed: verbs (send, register), nouns (inbox, history), and verb-object phrases (wait_message, list_agents). This reduces predictability compared to a unified verb_noun convention.

    Tool Count4/5

    Six tools is a reasonable size for an agent messaging bus, covering send, receive, polling, history, registration, and agent discovery. The slight redundancy between bus_inbox and bus_wait_message means one could potentially be removed, but the count is still well-scoped.

    Completeness4/5

    The toolset covers the core bus lifecycle: register agents, send and receive messages, wait for messages, view history, and list agents. Minor gaps exist, such as no explicit deregister/unregister operation or message acknowledgment mechanism, but these are not critical for basic bus functionality.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers