Skip to main content
The Bead is the WHAT primitive — a unit of work — and the bead store is the machinery that persists beads (tasks, messages, convoy members, and the ephemeral beads a formula run materializes). See How Gas City Works for where the Bead sits among the six. Gas City’s exec beads provider delegates each beads.Store operation to a user-supplied script, the same pattern the exec session provider uses for sessions. It makes the bead store a pluggable boundary: change one config line and Gas City persists beads through your script instead of the default bd (Dolt-backed) store.

Why

The default bd provider couples the store to a specific stack — the Go bd CLI wrapping a Dolt SQL database. A script backend lets you point Gas City at:
  • A different beads engine — for example beads_rust (br), a SQLite + JSONL hybrid with no JVM/Dolt dependency.
  • Custom persistence — bead writes that also trigger S3 snapshots, git commits, or other durability strategies.
  • Alternative databases — Postgres, SQLite, flat files, or any backend reachable from a CLI.

Usage

Select the provider in city.toml:
GC_BEADS overrides the config for a single command:
Resolution order is GC_BEADS → [beads] provider → bd (the default).

Calling Convention

The script receives the operation name as its first argument:
The script is exec’d directly — no shell. Mutations pass their payload as JSON on stdin; reads return JSON on stdout. Each invocation has a 30-second timeout. The script is spawned fresh per operation; there is no long-lived process to manage.

Exit Codes

Exit code 2 is the forward-compatibility mechanism: when Gas City adds an operation, an older script returns exit 2 and the provider treats it as a no-op success, so scripts only implement the operations they care about. The one exception is ready invoked with contract arguments (such as --include-ephemeral): there, exit 2 is surfaced as an error rather than a silent success, so runnable ephemeral beads are never quietly hidden from the orchestrator. A script that cannot serve those ready queries should exit 1 with a stderr message instead.

Operations

These are the subcommands a backend implements. Bead reads return a JSON array ([] when empty, never null). The remaining Store methods are composed by the provider from the subcommands above, so a script that implements this table supports them with no extra work:
  • ListOpen, ListByAssignee, ListByMetadata route to list; the provider applies the status/assignee/metadata filter after the script returns.
  • CloseAll is a sequence of close calls; SetMetadataBatch a sequence of set-metadata calls (neither is atomic — design scripts to be idempotent).
  • Tx runs its callback sequentially against the same store; writes are not grouped into a single transaction.
  • Ping runs list to confirm the script is reachable.

Optional operations

A script lists the optional operations it implements from capabilities; a script that exits 2 there offers none. import creates a bead under the id it already carries. Its stdin holds id, title, status, type, priority, created_at, updated_at, assignee, from, parent_id, ref, description, labels, metadata, ephemeral, no_history, defer_until, and close_reason, and the script must store the id, status, and timestamps exactly as given. When it prints nothing, the provider reads the bead back with get. The reverse storage migration (gc storage migrate --to-work or --to-rigs) copies beads back through import and refuses an exec store whose capabilities do not list it.

ready and ephemeral tiers

ready returns open, unblocked beads. The orchestrator’s demand scans pass --include-ephemeral, and the script must then include ephemeral run beads in its output; Gas City applies the caller’s tier filter after parsing. Future- deferred beads (defer_until in the future) are filtered at the store boundary, so a script may return them and let the provider drop them.

Wire format

Beads are exchanged as JSON matching the bd --json shape:
The script assigns id, status, created_at, and updated_at on create. On create the provider defaults a missing type to task before calling the script; on every read it normalizes a missing or empty status to open. metadata values may be any JSON type but are coerced to strings. A closed bead may carry close_reason, a string saying why it was closed (bd’s close_reason field); the provider reports it as the bead’s close reason and ignores it on a bead that is not closed. The close operation carries no reason; Gas City stamps metadata.close_reason before closing, so a script that records reasons can take it from there. Preserve ephemeral, no_history, and defer_until on every read path so the provider can keep run beads out of normal work queries. no_history=true marks durable work that carries no version-control history: unlike ephemeral beads it stays visible in issues-tier reads, and also appears in wisps-tier queries. Backends without native columns for these bits may store them internally (e.g. a private label) but must round-trip them as the matching JSON fields. The create request is a subset (title, type, priority, labels, parent_id, ref, needs, description, assignee, from, metadata, ephemeral, no_history, defer_until). The update request carries only the fields being changed (title, status, type, priority, description, parent_id, assignee, plus labels/remove_labels and a metadata overlay); omitted fields are left unchanged, and labels appends rather than replaces. dep-list returns objects of { "issue_id", "depends_on_id", "type" }.

Conventions

  • JSON on stdin for mutations avoids shell-quoting issues with titles, descriptions, and labels; set-metadata passes its value as raw stdin bytes so it can hold newlines, quotes, or JSON.
  • Not found → exit 1 with not found (or no issue found) on stderr; get, close, and reopen map that to the platform’s not-found error.
  • Idempotent writes — close on an already-closed bead should still exit 0; batch and transaction operations are not atomic.
  • Return supersets — list, children, and list-by-label should return every matching bead the script can see, including ephemeral ones; the provider applies the caller’s tier, query filters, and result limit after parsing (it always passes list-by-label a limit of 0).
  • Three-state status — the store vocabulary is open, in_progress, and closed. A backend with a richer status set maps the extras onto these three.

Environment Variables

The provider sets these before exec’ing the script: The parent environment is otherwise inherited, except that BEADS_* and GC_DOLT_* keys are stripped so a script cannot accidentally inherit the default store’s backend configuration.

Writing Your Own Script

  1. Start from contrib/beads-scripts/gc-beads-br as a template.
  2. Implement the operations your backend supports; let the provider compose the rest.
  3. Return exit 2 for operations you do not implement (but exit 1 for ready --include-ephemeral if you cannot serve it).
  4. Test with GC_BEADS=exec:./your-script gc status.

Minimal script (create / get / list)

Shipped Scripts

See contrib/beads-scripts/ for maintained implementations:
  • gc-beads-br — beads_rust (br) backend: SQLite + JSONL, no Dolt dependency. Dependencies: br, jq, bash.
  • gc-beads-k8s — runs bd inside a “beads runner” pod via kubectl exec, connecting to Dolt running as a StatefulSet in the cluster. Dependencies: kubectl, jq, bash.
The bundled bd provider itself ships an exec script (gc-beads-bd.sh) under the bd pack’s assets, which is how the default Dolt-backed store is driven through the same protocol.
Last modified on November 12, 2026