Beads 1.3.0 adds a change feed (bd events) and an HTTP API (bd serve)

[csells]

Hi @MikeBengtson 👋 — I'm on the Beads team. Thanks for building gemba. Your beads adapter pairs fsnotify on .beads with a 250ms ticker running bd list --json --updated-after against a timestamp high-water mark. bd events tail --follow gives you an ordered feed checkpointed by seq, so same-second updates aren't skipped and deletes arrive as records.

Beads 1.3.0 (release notes) has two features aimed at tools like yours. You can stop polling bd list and diffing snapshots.

bd events: an ordered change journal. While it's on, every change made through bd writes an ordered record to a journal, in the same transaction as the change. Each record carries the bead's full state after the change, so you can apply it without querying again. is_blocked is included only when it's true, so treat a missing field as false.

bd config set events-journal true          # opt-in, per workspace
bd events tail --since 0                   # JSON Lines, oldest first
bd events tail --since 4211 --follow       # resume from your checkpoint and keep following

{"seq":3,"ts":"...","op":"close","issue_id":"demo-399","actor":"...","issue":{"id":"demo-399","status":"closed", ...}}

The ops are create, update, close, delete, dep_add, dep_remove, and comment. Claims, reopens and label changes arrive as update, and a close or claim can also emit update records, with no actor, for other beads whose blocked state changed. Keep the highest seq you've processed and pass it back as --since.

bd serve: the same data over HTTP on loopback. You don't have to fork a bd process for every read.

bd serve --addr 127.0.0.1:7777
curl '127.0.0.1:7777/v0/beads/events?since=0&limit=500'   # paged: {"records":[...],"head":N}
curl -N '127.0.0.1:7777/v0/beads/events:watch?since=0'    # Server-Sent Events; resumes via Last-Event-ID

It also serves issues, ready work, dependencies, stats, and writes such as claim and close. GET /v0/beads/context lists what the running build supports, and the wire contract is in openapi.v0.yaml.

A few things to know before building on them:

• bd serve is still in preview, so for now it needs a Dolt server (server or proxied-server mode). It refuses the default embedded mode today; that will be fixed in a future version. Until then, embedded workspaces can use bd events tail or the CLI.
• The journal is off by default. bd config set events-journal true writes it to .beads/config.yaml, so every bd command in that workspace, agents included, is journaled from then on. Writes made through the beads Go library directly aren't. Over HTTP, a journal that is off returns 409 events_journal_disabled rather than an empty page, and a running bd serve keeps returning it until you restart it after turning the journal on.
• bd serve sends no CORS headers. A web page on another origin can't open events:watch directly, so a browser-based viewer should proxy it through its own backend.
• Each clone has its own sequence, and sync isn't journaled. Rebuild your view from current state after bd dolt pull, or when you switch to another clone.
• By default the journal keeps the last 7 days or the newest 100k records, whichever is more. A checkpoint that falls below what's retained gets events_journal_truncated (HTTP 410; the CLI exits 1). When that happens, rebuild from current state.
• 1.3.0 also changes some output and defaults you may depend on: bd dep cycles --json has a new shape, bd config list no longer lists kv. keys, and bd search now includes closed issues. See the release notes.

Full docs: Events Journal. If you try it, we'd love to hear how it goes, here or in the Gas Town Hall Discord. If you add support, send a PR to update your entry in community tools.

Chris Sells, Gas City