I build mAGI, a Fedora/Hyprland setup where the main interface is one agent (Claude Code, opencode, Codex or another terminal agent) running in tmux. It starts other agents and waits on things: a worker finishing, a local build page changing, a message in a browser tab.
A terminal agent only acts when text shows up in its input. So you either poll from inside the session, which spends tokens on "nothing new", or you type into it from outside and risk landing in the middle of a turn or on top of what the user is typing. mAGI's event bus is the second option with two checks in front of it.
The log
orch-bus emit build-2 "tests passed on promo branch" appends one JSON line to ~/.local/state/orchestrator/events.jsonl:
{"ts": "14:28", "at": 1794819500.5, "source": "build-2", "text": "tests passed on promo branch"} No broker and no port. Anything that can run a command can publish: workers, shell scripts, systemd timers. An optional --key dedupes repeats.
Delivery only when idle
orch-bus dispatch runs as a systemd user service. When the log grows it waits 3 seconds so a burst coalesces, then types everything pending into the orchestrator's tmux pane as one line:
[event bus] 14:28 build-2: tests passed on promo branch | 14:29 page-title: localhost:5173/: Build OK It only types if both are true:
- The agent's own state says idle. For Claude Code that's
~/.claude/sessions/<pid>.json, for opencode its local server API, for Codex its session rollout file. - The input box is empty. This is read from the pane, per agent, so a half-written message never gets text appended to it.
If either check fails, nothing is typed and the read offset doesn't move. Delivery is tmux send-keys -l with the text, then a separate Enter, because some agents show pasted text without submitting it if both go in one call.
BUS_DELIVERY=off turns typing off; the agent then reads with orch-bus unread, which keeps its own offset.
Workers use the same path
magi-agent spawn starts a worker in its own tmux window and watches it. "Finished", "waiting at a permission prompt" and "exited" go through the same idle gate, so the orchestrator never sleeps in a loop waiting for a worker.
Probes in the browser
mAGI runs a Chromium for agents with DevTools on 127.0.0.1:9222. browser-bus attaches over CDP and runs small probe scripts inside matching tabs, in an isolated world:
// @match http://127.0.0.1:*/* // @source page-title // @purpose Local dev servers: tell the bus when a page's title changes let last = null; const check = () => { const t = document.title.trim(); if (last !== null && t && t !== last) emit({ text: `${location.host}${location.pathname}: ${t}`, key: `${location.href}|${t}` }); last = t; }; ready(check); const timer = setInterval(check, 2000); return { stop() { clearInterval(timer); } }; A tab you're already signed in to becomes an event source, with no API and no screenshots from the agent's side. A probe can only emit under the source names in its header.
Untrusted text
Once probes relay messages other people wrote, bus text is untrusted input to an LLM. The guard (open PR, #1) gives each event a trust level, normalises the text (zero-width and bidi characters, homoglyphs for detection), scores it for injection patterns, and wraps external text in a fixed frame marked as data. High-risk events are delivered as a one-line summary with the full text quarantined, and a circuit breaker stops all typing until the owner runs orch-bus resume.
Related work
Others have built pieces of this: tmux orchestrators that detect a ready prompt from the pane (primeline-ai/claude-tmux-orchestration, twaldin/tmux-orchestrator), hook-based inboxes like agentqueue, plugin monitors that wake idle sessions, and a write-up on idle-gated commands.
The bus shipped in mAGI 0.2.0 on 15 Nov 2026. Code: agent/bin/orch-bus, agent/lib/browser-bus.mjs. Longer notes: docs/event-bus.md. MIT licensed; issues and adapters for other agents welcome.
