agent-bus

Agent Bus

SQLite-backed MCP channel for multi-agent coordination in Claude Code.

What it does

Multiple Claude Code agents share a single SQLite database as a message bus. When one agent makes a change (API contract, schema, deploy), it posts an announcement. Other agents receive it as a push notification via the MCP channel protocol.

Architecture

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Agent A       │    │ Agent B       │    │ Agent C       │
│ (Go backend)  │    │ (React FE)    │    │ (infra)       │
│               │    │               │    │               │
│ MCP channel ──┼────┤  bus.db       ├────┼── MCP channel │
│ (subprocess)  │    │  (SQLite WAL) │    │  (subprocess) │
└──────────────┘    └──────────────┘    └──────────────┘

Each agent spawns the bus as an MCP subprocess. All instances read/write the same SQLite file (WAL mode for safe concurrency). Messages are one-way announcements — agents listen and update their context, but don't reply to each other through the bus.

Requirements

• Bun (recommended) or Node.js 18+ with tsx
• Claude Code v2.1.80+
• Channels require claude.ai login (Console/API key auth not supported)

Installation

From the marketplace

/plugin marketplace add https://github.com/cryguy/agent-bus.git
/plugin install agent-bus@cryguy-plugins

Dependencies are auto-installed on session start via a SessionStart hook.

From a local clone

git clone https://github.com/cryguy/agent-bus.git
cd agent-bus && bun install  # or npm install
claude --plugin-dir ./agent-bus

Channel flag

The --dangerously-load-development-channels flag is required because agent-bus is not on the approved channel allowlist:

claude --dangerously-load-development-channels server:agent-bus

This flag is per-session.

Per-project setup

Each project that joins the bus needs its own .mcp.json entry with an agent name and a shared database path. Run the setup skill in your project:

/agent-bus:setup

This will ask for your agent name, database path, and runtime preference, then write the .mcp.json for you.

After updating the plugin, re-run /agent-bus:setup in each project. The setup skill detects stale paths and updates .mcp.json to point to the new version — no need to reconfigure from scratch.

Manual setup

Alternatively, add this to your project's .mcp.json directly:

Bun (recommended):

{
  "mcpServers": {
    "agent-bus": {
      "command": "bun",
      "args": ["/path/to/agent-bus/server.ts"],
      "env": {
        "AGENT_BUS_NAME": "backend",
        "AGENT_BUS_DB": "/shared/path/bus.db",
        "NODE_PATH": "/path/to/agent-bus/node_modules"
      }
    }
  }
}

Node.js:

{
  "mcpServers": {
    "agent-bus": {
      "command": "npx",
      "args": ["tsx", "/path/to/agent-bus/server.ts"],
      "env": {
        "AGENT_BUS_NAME": "backend",
        "AGENT_BUS_DB": "/shared/path/bus.db",
        "NODE_PATH": "/path/to/agent-bus/node_modules"
      }
    }
  }
}

Important: AGENT_BUS_DB must point to the same file across all agents that need to communicate.

Then start Claude Code with the development channel flag:

claude --dangerously-load-development-channels server:agent-bus

Configuration

Variable	Required	Default	Description
AGENT_BUS_NAME	Yes	—	This agent's identity (e.g. "backend", "frontend", "infra")
AGENT_BUS_DB	No	./bus.db	Path to shared SQLite database
AGENT_BUS_POLL_MS	No	5000	Poll interval in milliseconds
AGENT_BUS_TOPICS	No	all	Comma-separated topic filter. Supports wildcards, e.g. worker:*
AGENT_BUS_DISCORD_WEBHOOK	No	—	Discord webhook URL for @human notifications
AGENT_BUS_HUMAN_PORT	No	off	HTTP port for inbound human replies (localhost only)

Usage

Posting

When an agent changes an API endpoint, it uses the post tool:

topic: "api-change"
content: "Added GET /api/v2/users/:id/settings — returns { theme, notifications, timezone }"

Messages can be broadcasts (no target) or directed at a specific agent:

target: "frontend"
topic: "api-change"
content: "The /settings endpoint now returns timezone as an IANA string, not offset"

Receiving

Other agents see messages as channel notifications:

<channel source="agent-bus" sender="backend" topic="api-change">
Added GET /api/v2/users/:id/settings — returns { theme, notifications, timezone }
</channel>

The agent reads it, updates its understanding, and continues working.

History

Agents can read recent bus history using the history tool:

limit: 10
topic: "api-change"