waitbus

<!-- mcp-name: io.github.astrogilda/waitbus -->

# waitbus — the workstation-local, cross-harness status bus: D-Bus for agents, with a replay log and a wait primitive

[![CI](https://github.com/astrogilda/waitbus/actions/workflows/ci.yml/badge.svg)](https://github.com/astrogilda/waitbus/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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.

![waitbus cross-harness demo — two different agent frameworks on one local bus; one agent fails and the peer reacts](docs/demo/.waitbus-demo/hero.gif)

<sub>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 <code>make hero</code>; higher-quality MP4 at <a href="docs/demo/.waitbus-demo/hero.mp4"><code>hero.mp4</code></a>. For a gentler start, see the single-agent <code>waitbus demo</code> in <a href="#try-it-in-60-seconds">Try it in 60 seconds</a>.</sub>

---

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](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…**

- **You wait on one GitHub repo's CI and nothing else.** Use `gh run watch` —
  it's zero-setup, and for that single job we don't beat it by enough to
  justify a daemon.
- **You only need to react to a file change.** Use `inotifywait`/`entr` —
  they're far faster on raw filesystem latency (our own benchmark says so) and
  need no daemon.
- **You want cloud, cross-machine, or team coordination.** Out of scope for
  the local core by design.
- **You want addressed agent-to-agent messaging as the product** (threads,
  inboxes, routing). The headline here is broadcast source-ingestion; the
  `request()`/`respond()` facet exists, but a dedicated message queue serves
  that center of gravity better.

---

## Try it in 60 seconds

```bash
uvx waitbus demo          # one command, no install needed
```


`waitbus demo` allocates a temporary state directory and boots the
broadcast daemon, then runs two phases. **Phase 1 — the point:** an
agent blocks on `waitbus wait` (the same egress engine the real command
uses) with zero polling and idle CPU; the moment a github
`workflow_run` event lands, the wait returns and the demo prints the
real measured event-to-unblock latency. **Phase 2 — breadth:** the same
primitive delivers every source — `pytest_session`, `docker_container`,
and `fs_change` events fan out to a live subscriber. Nothing on your
machine outside the temporary directory is touched.

![waitbus single-agent demo — a blocking wait returns the moment a GitHub Actions workflow_run event lands, then prints the measured event-to-unblock latency](docs/demo/.waitbus-demo/demo.gif)

A recorded MP4 + GIF walkthrough lives at
`docs/demo/.waitbus-demo/demo.mp4` and `demo.gif`
(the tape script is `demo.tape`). Re-rendering is reproducible
via `make demo` from that directory (requires
[VHS](https://github.com/charmbracelet/vhs) ≥ 0.10.0, `ttyd`, and
`ffmpeg`); the `Makefile` enforces the VHS version floor and refuses
to render against an older binary that could silently change tape
semantics.

> The four events the demo emits are synthesized in-process — there
> is no real HTTP listener, no real pytest run, no real Docker
> daemon, no real watchdog. A banner before each emit makes this
> explicit, mirroring the `waitbus stats` output. To wire
> waitbus against real GitHub webhook deliveries, follow the Quick
> start below.

---

## Quick start

```bash
uv tool install waitbus          # install the package
waitbus init                     # one-time setup: state dirs, SQLite schema, scaffold files
waitbus install-credentials github-webhook-secret   # encrypt + stage HMAC secret via systemd-creds
waitbus install-systemd          # Linux: copy + enable the 8 systemd-user units
waitbus install-launchd          # macOS: copy + bootstrap the 4 LaunchAgent plists
waitbus read-events watch        # live tail of incoming events
```

`install-systemd` is Linux-only; `install-launchd` is macOS-only.
Each command refuses to run on the other platform and points at the
right one.

Once events are flowing, block any script or agent on the next
matching event with `waitbus wait` -- any source, any field, exit code
carries the verdict:

```bash
# pytest: wait for any session to finish (zero setup -- local source)
waitbus wait --source pytest --match 'fields.event_type="pytest_session"' --timeout 10m

# Docker: wait for a container to exit (zero setup -- local source)
waitbus wait --source docker --match 'fields.event_type="docker_container"' --timeout 30s

# Filesystem: wait for a watched path to change (zero setup -- local source)
waitbus wait --source fs --match 'fields.event_type="fs_change"' --timeout 5m

# GitHub CI: wait on a commit's terminal conclusion (needs webhook wiring -- see below)
waitbus wait --sha 7f3a1b2 --timeout 5m
```

If you have used [`watchexec`](https://github.com/watchexec/watchexec) or `entr` to
re-run a command when a file changes, `waitbus wait` is the same idea with a wider
net: it blocks on a file change too, but it can also wait on a CI run, a pytest
session, a container exit, or another agent's event, and hands the verdict back
through the exit code. The bus underneath also
fans every one of those events out to every other tool on the box.

---

## Architecture

```mermaid
%%{init: {'theme':'neutral','themeVariables':{'fontSize':'16px','fontFamily':'sans-serif'},'flowchart':{'nodeSpacing':28,'rankSpacing':46,'padding':14}}}%%
flowchart TB
    WH["<b>Webhooks</b><br/>GitHub · Alertmanager"]
    IP["<b>In-process</b><br/>pytest · docker · fs<br/>agents · plugins"]
    LS["<b>listener serve</b><br/>HMAC verify · etag-poll"]
    DB[("<b>SQLite event store</b><br/>seq PK<br/><code>INSERT&nbsp;OR&nbsp;IGNORE</code>")]
    BD["<b>broadcast daemon</b><br/>AF_UNIX&nbsp;fan-out<br/>doorbell&nbsp;wake · length-prefixed&nbsp;frames"]
    CLI["<b>CLI</b><br/><code>wait · on · top · read-events</code>"]
    MCP["<b>MCP server</b><br/><code>mcp serve</code>"]
    SDK["<b>Python SDK</b><br/><code>subscribe · wait_for</code>"]

    WH -->|webhook| LS --> DB
    IP -->|emit| DB
    DB -->|doorbell| BD
    BD --> CLI
    BD --> MCP
    BD --> SDK
    C