turnbus
Integrates with OpenAI Codex CLI via its local app-server-control socket to discover loaded threads, steer active turns, and queue or start idle turns while respecting approval gates.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
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.
Active Turn Wakeup & Busy-Session Steering:
Claude Code (
claude): Emits session-boundnotifications/claude/channelnotifications 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/steerwithexpectedTurnId), or queues and starts idle turns (thread/queue/add+thread/queue/startwithqueuedSubmissionId) while respecting approval gates (waitingOnApproval).Antigravity CLI (
agy): Pushes messages viaagy agentapi send-messageusing session-scoped language server coordinates (ANTIGRAVITY_LS_ADDRESS&ANTIGRAVITY_CSRF_TOKEN).
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).
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
@handledelivers passively (0LLM tokens spent); mentioning@handle(outside fenced code blocks and blockquotes) wakes only the mentioned member(s).
Loop Protection & Token Conservation:
Built-in sliding-window wake rate limiter (default
15wakes/min per recipient), unbroken agent-to-agent reply-chain depth cap (10hops), and a global Pause Pushes switch in the Web UI and CLI.
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 |
|
|
|
SQLite WAL Durable Inbox & Channels | Yes | Yes | Partial |
Claude Code Native Channel Wakeup | Yes | No (poll) | Hooks only |
Codex Active-Turn Steering ( | Yes | No | No |
Antigravity | Yes | No | No |
Parallel Fan-Out with Reply Barrier ( | Yes | No | No |
Mention-Gated Channel Wake ( | Yes | N/A | No |
Per-Session Token Fencing & Loopback | Yes | No | No |
Quickstart
1. Install & Run Tests
bun install
bun test2. 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 uiOpen 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:
Claude Code (
--dangerously-load-development-channels server:turnbus):Claude Code's
notifications/claude/channelnotification path requires launchingclaudewith--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>/statstart-time verification.If launched without that flag,
turnbusautomatically detectspushCapability: "none"and degrades gracefully to standard MCPcheck_messages()inbox reads.
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,turnbusholds messages safely in the SQLite inbox (status = 'queued') rather than dropping them.
Antigravity CLI (
agy agentapi send-message):Antigravity wakeup uses
agy agentapi send-message, which requires the session'sANTIGRAVITY_CONVERSATION_ID,ANTIGRAVITY_LS_ADDRESS, andANTIGRAVITY_CSRF_TOKEN. Because Antigravity does not passANTIGRAVITY_LS_ADDRESSto stdio MCP child processes, runturnbus registeronce from the agent's shell tool (or wire an Antigravity hook) so the daemon can cache the coordinates in<stateDir>/agy-creds.json(0600).
Same-UID Local Security Boundary:
turnbusbinds strictly to127.0.0.1, validatesHost,Origin, andSec-Fetch-Siteon every HTTP/WebSocket request, separatesagent.tokenfromui.token, and requires per-sessionx-turnbus-session-tokenheaders 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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables multiple AI agents to communicate and coordinate via a shared SQLite-backed message log, supporting directed messages, broadcasts, and session discovery.-
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables two local coding-agent sessions to exchange tasks, reports, and blockers over named channels with enforced turn ownership, session recovery, and SQLite-backed state.MIT