waitbus — the workstation-local, cross-harness status bus: D-Bus for agents, with a replay log and a wait primitive
One wait verb that blocks on, and queries across, every local source at once. When any agent, CI job, test, or container on your machine finishes or fails, every other tool on the box hears it: your Claude Code, your Cursor, your scripts, your CI. Clients that support server notifications get a push; the rest get one blocking waitbus wait. No waitbus cloud, no account, no telemetry — all processing stays on your machine.
Below: a Pydantic AI agent and a LangGraph agent — two different frameworks, two separate OS processes — both wait on one local waitbus bus. One fails; the peer on the other framework, plus a live waitbus top view, react to the single failure broadcast.
Real frameworks and real waitbus subscribe/emit; the agents' LLMs are deterministic fakes and the failure is an injected event, so the clip runs fully offline. Reproduce with make hero; higher-quality MP4 at hero.mp4. For a gentler start, see the single-agent waitbus demo in Try it in 60 seconds.
waitbus is the workstation-local, cross-harness status bus that lets the
tools on one machine hear each other. It does three things: ingest events,
broadcast them, and replay them.
Ingest: a blocking wait/emit primitive lets any agent or script
(across Cursor, Claude Code, and any tool on the box) wait on, or emit, events
from five built-in sources (GitHub Actions CI, pytest sessions, Docker
container lifecycle, filesystem changes, and Prometheus Alertmanager) plus any
plugin source registered under the waitbus.sources.v1 entry-point group.
Broadcast: events land in SQLite the moment they arrive, and a broadcast
daemon fans each row to every connected consumer within about a
millisecond on the local socket (measured; see benchmarks/BENCHMARKING.md). Your
agent blocks on waitbus wait (including across sources at once with
--all-of/--first-of) with zero agent-side polling and idle CPU until the thing it
cares about happens, and waitbus on <predicate> -- <command> runs a command
the moment it does (in the CLI process, not the daemon, via execve with no
shell; event values arrive as namespaced WAITBUS_* environment variables and
a $WAITBUS_EVENT_FILE, never as argv, so event content cannot inject flags
or overwrite PATH). Because every agent on the box shares that one bus, it
doubles as a same-machine coordination backplane: one agent emits, the others
wake.
Replay: a durable replay log (since=) means a consumer that was
offline catches up instead of missing the moment, and waitbus events analyze
queries what the bus stored. It is the local opt-in
event-broadcast model the OS already uses (D-Bus signals, inotify, journald),
with the replay log and a wait predicate added on top. (GitHub Actions was
the first source wired, which is why the examples lead with CI, but waitbus is
not CI-only.) The dependency stack is lean: typer, msgspec, platformdirs,
pydantic-settings, prometheus_client, stamina, and the mcp SDK, with no
heavy TUI or crypto dependency. The daemon idles at roughly 40 MB RSS measured
(p50 on the benchmark host, most of it the CPython interpreter baseline) over
a SQLite event store and an AF_UNIX SOCK_STREAM broadcast bus with
length-prefix framing. Runs on Linux (systemd-user) and macOS (launchd).
Who this is for
This is for you if…
- You run a heterogeneous agent fleet — Claude Code and Cursor and
background scripts — on one workstation and want them to hear each other's
finishes and failures.
- You wait across sources — "block until the tests pass and the build is
done and CI is green," in one predicate, in a script
(
waitbus wait --all-of ...). Nothing else expresses this.
- You want zero-LLM-token, zero-poll waiting as a daily habit across many local
things, and you'll run a daemon to get it.
- You care that the daemon on your box is trustworthy — reproducible
builds, offline, no cloud, no account, no telemetry.
This is NOT for you if…
