Lucent Owl logo Lucent Owl

Beads Architecture Diagrams

Last updated:

2 related guides
beads dolt dependency-graph agent-memory c4 architecture-diagrams

Beads Containers in One Repository

C4 · Container

What lives in a clone, and how bead history syncs.

Beads container diagram for one repository A C4 container view of one clone. The coding agent runs the bd CLI and receives context from bd prime. bd reads its config and writes to a Dolt database that auto-commits every write. The Dolt database pushes and pulls bead history to its own ref, refs/dolt/data, on the same git origin that holds the source branches. The optional JSONL export is refreshed by the pre-commit hook and is not a sync path. ONE CLONE OF THE REPOSITORY Coding agent [Container: Claude Code, Codex, …] runs bd in its own shell AGENTS.md or CLAUDE.md [File: written by bd setup] the start-work-end discipline bd [Container: Go CLI] ready · claim · close · prime Dolt database [Store: version-controlled SQL] every write auto-commits .beads/config.yaml [Config: tracked in git] mode, prefix, sync.remote .beads/issues.jsonl [Export: optional, passive] refreshed by the pre-commit hook Git hooks [Shims: bd hooks run] pre-commit, post-merge, pre-push Source code [Git working tree] commits go to refs/heads/* git origin [External: GitHub, GitLab, …] refs/dolt/data bead history, its own ref bd dolt push / pull Two refs, one remote a plain git clone skips refs/dolt/data, so a new clone runs bd bootstrap refs/heads/* source branches git push / pull runs bd prime reads SQL reads ✗ not a sync path calls, reads and writes context or config read anti-pattern external system

Where a Beads Claim Is Atomic

C4 · Deployment

Claiming a bead in embedded clones versus one shared server.

Beads deployment topologies and the reach of an atomic claim Two panels. Across clones in embedded mode, each clone has its own local Dolt database and a claim is atomic only inside that database, so two agents can both claim the same bead before either pushes and the collision surfaces only at merge time. On one machine in server mode, every agent writes through one dolt sql-server to one database, so the first claim wins. Inside Gas City, one server serves the whole city and each rig is an issue prefix on it. ACROSS CLONES · EMBEDDED MODE git origin refs/dolt/data Clone A local Dolt database agent 1 claims here claim is atomic Clone B local Dolt database agent 2 claims here claim is atomic bd dolt push / pull ✗ both claim bd-a1b2 before either pushes Dolt merges cell by cell, so the collision surfaces only at merge: as a conflict, or as a silent merge of two identical claims. A change stays local until it is pushed. ONE MACHINE · SERVER MODE agent 1 agent 2 agent 3 dolt sql-server [Process: many writers] one database one shared ready frontier first claim wins Every claim runs against the same database, so claiming is a true lock. Parallel agents on one backlog belong here. Inside Gas City one server serves the whole city, and each rig is an issue prefix on it, not a database sync or SQL where a claim is atomic

The Ready Frontier

Dependency graph

How each edge type decides what bd ready returns.

How edge types decide the ready frontier of a Beads work graph An epic contains five child beads. The closed schema bead blocks the API and migration beads; the API bead is ready and the migration bead is claimed. The rollout bead is blocked by the API, the migration, and a gate waiting on a pull request. A rollback bead is linked by conditional-blocks and runs only if the rollout fails. A flaky-test bead, filed during the migration with a discovered-from edge, sits outside the epic and is ready, because discovered-from never blocks. bd ready returns exactly the API bead and the flaky-test bead. EPIC BD-A3F8 · CONTAINMENT IS THE PARENT-CHILD EDGE bd-a3f8.1 schema closed bd-a3f8.2 API blockers all closed bd-a3f8.3 migrate claimed by agent-2 bd-a3f8.4 rollout waits on .2, .3, gate gate: PR #412 clears when it merges bd-a3f8.5 rollback only if rollout fails bd-7c1e flaky test filed mid-task discovered-from bd ready returns bd-a3f8.2 and bd-7c1e: the frontier .3 is claimed, .4 waits on three blockers, and .5 becomes ready only if .4 fails blocks gate check conditional-blocks: runs on failure discovered-from: provenance only ready frontier in progress closed blocked

Workflow Phases: Formula to Molecule

Flow

Formula to proto to molecule or wisp.

The Beads workflow phases from formula to molecule or wisp A formula file is cooked into a proto, a template epic that is the solid phase. Pouring the proto produces a molecule, persistent beads in the liquid phase that sync like any bead. Wisping it produces a wisp, ephemeral beads in the vapor phase that are not federated and are purged after closing. A wisp that found something worth keeping is squashed into a permanent digest; otherwise it is burned. Below, a molecule is shown as what it is underneath: an epic whose child steps are wired by the formula's needs, run in parallel unless a dependency or a gate holds them back. SOURCE SOLID · TEMPLATE LIQUID · PERSISTENT VAPOR · EPHEMERAL formula [TOML or JSON file] steps, needs, variables proto [Epic, template label] variables unfilled molecule [Epic + child beads] synced like any bead steps flow through bd ready like any other work wisp [Ephemeral beads] not federated, purgeable closed: bd purge or wisp GC digest permanent deleted no record bd cook bd mol pour bd mol wisp squash burn A MOLECULE IS AN EPIC WHOSE CHILDREN ARE WIRED BY NEEDS root epic children run in parallel unless a need holds them step .1 design step .2 docs step .3 build gate: human ok step .4 release command or blocks edge gate children of the root epic

Found this useful? Share it:

Share on LinkedIn