Skip to main content
Glama

turnbus — Local Multi-Agent Turn Bus & MCP Switchboard

turnbus is a lightweight, SQLite-backed local message bus and Model Context Protocol (MCP) server for coordinating multiple concurrent CLI coding agents (Claude Code, OpenAI Codex CLI, Antigravity CLI) and a human operator console.

Unlike passive mailbox MCP servers that require agents to poll in a loop, turnbus actively wakes idle agent turns and steers active sessions while keeping unmentioned group traffic completely passive (0 LLM tokens).


Key Features

  1. Dynamic Zero-Config Roster:

    • No hardcoded agent names or paths. Agents self-register when their MCP server starts (<tool>-<folder> by default, or --handle <name> / TURNBUS_HANDLE=<name>).

    • Rename handles, set capitalized display names, or persist workspace defaults (workspace + tool -> handle) at runtime via MCP (rename_agent), CLI (turnbus rename), or the Web UI.

  2. Active Turn Wakeup & Busy-Session Steering:

    • Claude Code (claude): Emits session-bound notifications/claude/channel notifications over WebSocket when launched with --dangerously-load-development-channels server:turnbus.

    • OpenAI Codex CLI (codex): Discovers loaded threads via ~/.codex/app-server-control/app-server-control.sock, steers active turns (turn/steer with expectedTurnId), or queues and starts idle turns (thread/queue/add + thread/queue/start with queuedSubmissionId) while respecting approval gates (waitingOnApproval).

    • Antigravity CLI (agy): Pushes messages via agy agentapi send-message using session-scoped language server coordinates (ANTIGRAVITY_LS_ADDRESS & ANTIGRAVITY_CSRF_TOKEN).

  3. First-Class Fan-Out Messaging (fanout_message & check_fanout):

    • Dispatch a prompt or review request to N agents in parallel with a single call and optionally await correlated replies across a barrier (wait_for: "all" | "any" | k).

  4. Runtime Group Channels with Mention-Gated Wakeups:

    • Create, join, leave, and archive channels at runtime (create_channel, join_channel, leave_channel, archive_channel).

    • Posting to a channel without @handle delivers passively (0 LLM tokens spent); mentioning @handle (outside fenced code blocks and blockquotes) wakes only the mentioned member(s).

  5. Loop Protection & Token Conservation:

    • Built-in sliding-window wake rate limiter (default 15 wakes/min per recipient), unbroken agent-to-agent reply-chain depth cap (10 hops), and a global Pause Pushes switch in the Web UI and CLI.

  6. Real-Time Operator Web UI (http://127.0.0.1:8790):

    • Live delivery state pills (queued $\rightarrow$ pushed $\rightarrow$ acked), DM/Channel/Fan-Out composer, runtime channel & handle management, and a toggleable Auto-scroll: ON/OFF stream viewer.


Related MCP server: agent-bridge

How turnbus Compares to Existing Projects

Capability

turnbus

mcp_agent_mail / agmsg

hcom

SQLite WAL Durable Inbox & Channels

Yes

Yes

Partial

Claude Code Native Channel Wakeup

Yes

No (poll)

Hooks only

Codex Active-Turn Steering (turn/steer)

Yes

No

No

Antigravity agentapi Turn Wakeup

Yes

No

No

Parallel Fan-Out with Reply Barrier (all/any/k)

Yes

No

No

Mention-Gated Channel Wake (0 tokens when unmentioned)

Yes

N/A

No

Per-Session Token Fencing & Loopback Sec-Fetch-Site Guard

Yes

No

No


Quickstart

1. Install & Run Tests

bun install
bun test

2. Configure Your Agents' MCP Settings

Add turnbus to your agent CLI MCP configuration:

{
  "mcpServers": {
    "turnbus": {
      "command": "bun",
      "args": ["run", "/path/to/turnbus/src/mcp-server.ts"]
    }
  }
}

(Optional: pass "--handle", "reviewer", "--display-name", "Reviewer" in args or set TURNBUS_HANDLE=reviewer.)

3. Open the Operator Web UI

bun run src/cli.ts ui

Open the printed http://127.0.0.1:8790/#token=... URL in your browser. The UI token is stored in localStorage and stripped from the URL bar automatically.


Platform Internals & Fragile Dependencies (Honest Disclosure)

turnbus achieves zero-polling turn wakeup across three closed/semi-closed vendor CLIs by integrating with their local control interfaces. Keep these platform constraints in mind:

  1. Claude Code (--dangerously-load-development-channels server:turnbus):

    • Claude Code's notifications/claude/channel notification path requires launching claude with --dangerously-load-development-channels server:turnbus (a research-preview flag in Claude Code $\ge 2.1.x$) and discovers the parent session via ~/.claude/sessions/<pid>.json + /proc/<pid>/stat start-time verification.

    • If launched without that flag, turnbus automatically detects pushCapability: "none" and degrades gracefully to standard MCP check_messages() inbox reads.

  2. OpenAI Codex CLI (~/.codex/app-server-control/app-server-control.sock):

    • Codex push delivery speaks JSON-RPC over Codex's local app-server-control.sock (thread/loaded/list, thread/read, turn/steer, thread/queue/add, thread/queue/start, config/mcpServer/reload). If future Codex releases change this internal RPC schema, turnbus holds messages safely in the SQLite inbox (status = 'queued') rather than dropping them.

  3. Antigravity CLI (agy agentapi send-message):

    • Antigravity wakeup uses agy agentapi send-message, which requires the session's ANTIGRAVITY_CONVERSATION_ID, ANTIGRAVITY_LS_ADDRESS, and ANTIGRAVITY_CSRF_TOKEN. Because Antigravity does not pass ANTIGRAVITY_LS_ADDRESS to stdio MCP child processes, run turnbus register once from the agent's shell tool (or wire an Antigravity hook) so the daemon can cache the coordinates in <stateDir>/agy-creds.json (0600).

  4. Same-UID Local Security Boundary:

    • turnbus binds strictly to 127.0.0.1, validates Host, Origin, and Sec-Fetch-Site on every HTTP/WebSocket request, separates agent.token from ui.token, and requires per-session x-turnbus-session-token headers once a handle is bound.

    • However, if all local agents run under the same OS Unix user without container/UID sandboxing, any process with full filesystem access can read ~/.local/share/turnbus/ui.token. For hard multi-tenant isolation against untrusted local processes, run agents under separate Unix UIDs or sandboxes.


License

MIT License

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables multiple AI agents to communicate and coordinate via a shared SQLite-backed message log, supporting directed messages, broadcasts, and session discovery.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Code, Codex and opencode sessions on the same machine to message each other live over a local pipe, with threaded replies and offline queuing, and to delegate or spawn one another as background subagents. Messages persist in SQLite and any running server can take over as broker, so peers stay reachable without a daemon.
      97 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding-agent sessions on the same machine to collaborate locally and durably by exchanging requests, replies, and task results through an authenticated loopback server with SQLite-backed storage, joined via CLI or an MCP stdio bridge. It also handles message delivery by priority and wait time, deduplicates idempotent sends, enforces task versioning, and preserves artifacts by content hash.
      12 npm
      Apache 2.0