A multi-agent message bus exposed as an MCP server. Multiple AI coding agents (Claude Code, OpenCode, Cursor, Codex CLI, …) connect to one long-lived process and coordinate through direct messages, broadcasts, and a shared task list — with atomic operations, structured schemas, long-poll waits, and an SSE stream for plugins.
This replaces the brittle "agents write JSON files to a shared folder" pattern with a real bus: SQLite (WAL) for persistence, an in-process event emitter for wake-ups, and a clean set of typed tools.
- One shared process, HTTP transport. All agents connect over Streamable HTTP to the same process so they share one DB and one event stream — not stdio-per-agent.
- Identity is fixed per connection. Each agent sets
x-agent-idin its MCP server config. The server reads it from a header on every request. Requests with no identity are rejected. Agents can't claim another identity per-call — the sender of every message and the claimer of every task is the header value, never a tool argument. - SQLite with WAL.
journal_mode=WAL,synchronous=NORMAL— concurrent reads + serialized writes, no extra infrastructure. WAL status is logged at startup. Uses Node's built-innode:sqlite, so there's no native addon to compile — install just works on any platform (requires Node 24+). - Long-poll, not WebSocket.
wait_for_messageblocks (up to a timeout) and resolves the moment a message arrives, via an in-memory emitter keyed by agent ID. - SSE for plugins.
GET /events?agent_id=Xstreams events to non-MCP clients (the OpenCode plugin, watchers, dashboards) off the same emitter. - All timestamps are unix epoch milliseconds (integers).
Requires Node 24+ (for the built-in node:sqlite module).
npm install
npm run build
node dist/index.js # listens on 127.0.0.1:4319 by defaultEnvironment variables:
| Var | Default | Purpose |
|---|---|---|
AGENT_BUS_DB_PATH |
./agent-bus.db |
SQLite file path |
PORT |
4319 |
HTTP port |
HOST |
127.0.0.1 |
Bind address |
LOG_LEVEL |
info |
pino log level |
Endpoints: POST /mcp (MCP), GET /events (SSE), GET /health.
Every request to /mcp must carry x-agent-id: <your-agent-id>. It is set once in your MCP client config and identifies you for the life of the connection. Without it the server returns 401. Optionally pass x-agent-metadata as a JSON string (e.g. role/model) which whoami and list_agents return.
claude mcp add --transport http squish http://localhost:4319/mcp \
--header "x-agent-id: backend-1"Give each agent a distinct ID (backend-1, frontend-1, reviewer, …).
opencode.json (see examples/opencode.json) — reference the identity from the environment so one config serves every agent:
{
"mcp": {
"squish": {
"type": "remote",
"url": "http://localhost:4319/mcp",
"enabled": true,
"headers": {
"x-agent-id": "{env:AGENT_ID}",
"x-agent-metadata": "{env:AGENT_METADATA}"
}
}
}
}{env:VAR} is substituted from OpenCode's process environment (not from a .env file — those aren't auto-loaded). x-agent-metadata is optional JSON returned by whoami/list_agents (e.g. role); leave AGENT_METADATA unset to omit it.
AGENT_ID identifies the agent and must be unique per running instance — it is read in two places that must agree: the x-agent-id MCP header (above) and the companion plugin's SSE connection. Set it in the environment that launches OpenCode; do not commit a shared .env (it can only hold one id, and OpenCode/Node don't auto-load .env anyway). Pick whichever fits your workflow:
# 1. Inline at launch (simplest — one agent per terminal)
AGENT_ID=backend-1 opencode
AGENT_ID=frontend-1 AGENT_METADATA='{"role":"frontend"}' opencode
# 2. Per-role shell alias
alias oc-backend='AGENT_ID=backend-1 opencode'
# 3. direnv per worktree — gitignored .envrc, auto-exported into the shell:
# echo 'export AGENT_ID=backend-1' > .envrc && direnv allowIf AGENT_ID is unset, the bus rejects every MCP call with 401, and the plugin prints a warning and disables itself.
whoami— your agent ID + registration metadata; refresheslast_seen.list_agents{ active_within_seconds=300 }— agents seen recently.
send_message{ to, body, subject?, metadata? }→{ message_id, created_at }.broadcast{ body, subject?, metadata? }→{ message_id, recipients[], created_at }— to all known agents except you.get_inbox{ unread_only=true, limit=50, since? }→{ messages[] }. Does not mark read.mark_read{ message_ids[] }→{ marked }. Read state is per recipient (broadcasts included).wait_for_message{ timeout_seconds=30, unread_only=true }→{ messages[], timed_out }. Returns immediately if unread messages exist; otherwise blocks until one arrives or the timeout elapses.
create_task{ title, description?, depends_on?, metadata? }→{ task_id, created_at }. IDs are ULID-style (sortable).list_tasks{ status?, assignee?, include_completed=false }→{ tasks[] }.claim_task{ task_id }→{ claimed, task?, reason? }. Atomic and race-safe — exactly one agent wins.reason∈already_claimed | not_found | dependencies_pending.update_task_status{ task_id, status, notes?, result? }— only the assignee may update; completing a task fires an event so dependents can be picked up.
Tool results are returned as JSON text (content[0].text), parseable by any MCP client.
GET /events?agent_id=X (or send the x-agent-id header — preferred, but EventSource can't set headers, so the query param is accepted). Standard SSE frames:
| Event | Data |
|---|---|
message |
{ message_id, from, subject, preview } (≤200 chars) |
task_created |
{ task_id, title } |
task_claimed |
{ task_id, assignee } |
task_completed |
{ task_id, assignee, result_preview } |
heartbeat |
{ ts } every 25s |
message events are filtered per subscriber: direct messages reach only the recipient; broadcasts reach everyone except the sender.
There are two ways agents consume work off the bus — pick per your use case:
- Pull / autonomous worker (recommended for active collaboration). The agent's instructions tell it to loop:
wait_for_message, handle it, repeat (and claim tasks offlist_tasks). The agent drives itself and reacts the moment work arrives — no plugin needed, because it's already actively waiting. Seeexamples/AGENTS.mdfor a drop-in worker-loop prompt. This is the right model when you want agents that do work as messages arrive. - Push / nudge-when-idle. A companion plugin watches the SSE stream and, when a message arrives while the session is idle, injects a prompt telling the agent to read its inbox. Good for mostly human-driven agents that just need a heads-up. Note the turn-based limit: it can wake an idle agent but cannot interrupt one mid-task (the message is queued and delivered once it next goes idle).
examples/opencode-plugin.ts is the companion plugin: it consumes /events (via fetch streaming), and when a message event arrives while the session is idle, it prompts the session to go read its inbox. Drop it in .opencode/plugin/ and set AGENT_ID (see above). Set SQUISH_DEBUG=1 for verbose [squish] logging. Not needed in worker-loop mode — there the agent receives messages directly through wait_for_message.
Claude Code equivalent: the same idea translates to a wrapper script invoked by a hook. A SessionStart (or Notification) hook runs a small script that long-polls wait_for_message; when it returns messages, the script emits a notification / injects context telling the agent to call get_inbox. The bus side is identical — only the client-side glue differs.
node dist/index.js &
npx @modelcontextprotocol/inspector
# Connect via Streamable HTTP to http://localhost:4319/mcp
# Add header x-agent-id: tester → exercise every tool.npm test # vitest: messaging, tasks, long-poll, claim_task race
npm run typecheck
npm run dev # node --watch on src/index.tsOut of scope by design: auth beyond x-agent-id (run on localhost or behind your own layer), TLS (terminate elsewhere), multi-host/clustering (single process; swap SQLite for Postgres + Redis pub/sub if you outgrow it), first-class message threading (use metadata.in_reply_to), and any UI.