Beads — The Git-Versioned, SQL-Queryable Work Primitive

Source: Steve Yegge's Gas Town blog series (posts 1–4), Jan–Apr 2026
Code: github.com/gastownhall/beads (20k GitHub stars as of Apr 2026)
Related: steve-yegge-gas-town, steve-yegge-gupp, steve-yegge-meow

What Is a Bead?

A Bead is the atomic unit of work in the Gas Town / Gas City ecosystem. Every discrete unit of work — a code task, a message, a coordination signal, a patrol route, a quality gate — is a Bead. Beads are git-versioned and stored in Dolt, a Git-for-SQL database that combines the versioning semantics of git with the queryability of a relational database.

The core insight behind Beads is that git stores the wrong four fields for agentic work. Git records:

  • What changed
  • Where (which files/lines)
  • Who made the change
  • How it was made (the diff)

But for AI-augmented software development, none of those are the hard part. The hard part is Why — the intent, the reasoning chain, the decision history. Why was this approach chosen over that one? Why does this fix address the root cause? Why was this trade-off accepted?

Beads capture Why. Every Bead is a git commit that stores the intent and reasoning alongside (or instead of) the mechanical diff. This completes the data-warehousing picture that agentic systems need for forensic analysis, onboarding new team members, recovering from failures, and auditing.

Beads as Universal Data Plane

In Gas Town, Beads are not just for tracking project tasks. They are the universal data plane — the single medium through which all work, coordination, and messaging flows.

Concretely, this means:

  • Project tasks are Beads (epics decomposed into bead sequences)
  • Orchestration flows are Beads (the Mayor's handoff instructions to the Refinery)
  • Messages between agents are Beads (with full context preserved)
  • Patrol routes for the Deacon daemon are Beads (structured work items the Deacon assigns to itself)
  • Quality gate results are Beads (Witness output recorded as structured data)
  • Reputation stamps from the Wasteland are Beads

Because everything is a Bead, everything is git-versioned, branchable, queryable, and auditable. Dolt's SQL interface means you can run queries like:

SELECT bead_id, author, reason, status
FROM beads
WHERE type = 'quality_gate'
  AND created_at > '2026-04-01'
  AND reason ILIKE '%security%';

This is the forensic foundation that makes a dark factory trustworthy. Every action taken by every agent is logged, versioned, and queryable — not in some opaque activity feed, but in a database your existing tooling already understands.

Why Beads Over Plain Git Commits?

The question naturally arises: why not just use git commits? Yegge's answer is that git commits are the wrong abstraction for intent tracking:

  1. Commits are anonymous by default. Anyone can amend, rebase, and overwrite history. Beads are immutable once finalized, with change tracked via explicit forking and merging (Dolt's model).

  2. Commits have no typed structure. A commit is a blob of diff + metadata. A Bead has typed fields: type, status, reason, parent_bead_id, author, created_at. You can query across them.

  3. Commits have no state machine. A Bead moves through explicit states: pending → running → done (or failed). You can track work-in-progress, blockers, and completions structurally.

  4. Commits don't capture Why. The Bead's reason field is the answer to "why was this work item created?" — stored permanently, not lost in a commit message that will be rewritten or lost in a merge.

  5. Commits don't compose into workflows. Bead sequences (epics) are ordered chains of related Beads that represent a complete unit of work flowing through the system. Git has no equivalent.

Beads and the Wasteland

Beads are the substrate for the Wasteland's reputation economy. When a Rig completes work in the Wasteland (see steve-yegge-wasteland), the requesting party issues stamps — multi-dimensional attestations (quality, reliability, creativity) — as Beads attached to the original work item. The immutable, queryable Bead history means any party can audit a Rig's track record by querying its completed Beads.

The "yearbook rule" of the Wasteland — you can't stamp your own work — is enforced structurally: stamps are separate Beads authored by the validator, not the worker.

MEOW: Beads as Currency

Beads are the foundation of MEOW (Molecular Expression of Work), Yegge's framework for making Work the first-class system primitive. Under MEOW, Beads become the unit of value in the Wasteland economy: work is requested, priced, executed, and compensated in Beads. See steve-yegge-meow for full treatment.

Kelly Parallel

Beads Concept Kelly Equivalent
Bead as atomic work item Kelly's work-item tracking — each task in the pipeline has an associated work item
Bead's reason field (Why) Kelly's TEA audit trail — reasoning logged alongside actions for forensic reconstruction
Immutable, versioned Beads Kelly's done markers per subphase — explicit state transitions that create a paper trail
Dolt SQL queryability Kelly's pipeline state — structured state query, but Beads' Dolt is far more powerful
Epics as Bead sequences Kelly's subphase → action chain — ordered work items flowing through pipeline stages
Stamps as attached Beads Kelly's multi-agent attestations (e.g., 5-agent verdict) — external validation recorded on the work item
Bead authorship (who did it) Kelly's agent attribution — which agent performed which action

Key gap: Kelly has no equivalent to the Bead's universal data plane. In Kelly's system, work items, messages, quality gates, and patrol routes are tracked in separate mechanisms (memory, heartbeat, pipeline state, TEA audit). Beads would unify these into a single git-versioned, SQL-queryable store. This is a significant architectural simplification.

Key distinction: Kelly's TEA audit captures reasoning alongside actions but is not designed to be the work item itself. Beads make the reasoning the primary citizen, not a sidecar. A Bead is the work; its git history is the audit.

Source Attribution

All Beads design discussion from Steve Yegge's Gas Town series:
- "Welcome to Gas Town" — Jan 1, 2026 — introduces Beads as universal data plane
- "Gas Town Emergency User Manual" — Jan 13, 2026 — MEOW framework introduced
- "Gas Town: from Clown Show to v1.0" — Apr 3, 2026 — Beads recharacterized as "The Missing Why"; 20k GitHub stars announced
- "Welcome to Gas City" — Apr 24, 2026 — Beads formalized as the work primitive underlying all packs

Bibliography

steve-yegge-gas-town, steve-yegge-gupp, steve-yegge-meow, steve-yegge-wasteland