Beads - A memory upgrade for your coding agent https://beads.gascity.com
  • Go 95.2%
  • Python 1.6%
  • Starlark 1.5%
  • Shell 1.3%
  • Rust 0.2%
Find a file
CI Bot 4b68fd30f5 feat(events): bd events CLI, activation config, and the consumer golden (bd-opisf)
`bd events tail|export|prune` is how a consumer actually reaches the journal.
tail emits JSONL from a --since checkpoint and --follow keeps printing new
records as they commit; export is tail from zero; prune deletes below --before,
honoring the retention floors. All three work identically against the embedded
store, a server-mode store, and proxied-server mode, which reads and prunes
through its unit-of-work journal capability rather than a raw connection. The
proxied prune commits with the SQL-only form: the journal table is dolt_ignored,
so its delete must persist into the working set without minting a Dolt commit.

A pruned-past checkpoint surfaces as {"code":"events_journal_truncated","since",
"floor","head"} with a non-zero exit. Both read call sites report it, because
wiring only one still lets `export` present a pruned journal as a complete
history — and the two are framed differently on purpose. The one-shot read
prints the object the way every other --json failure does. The --follow poll
prints it as ONE line on the JSONL stream it interrupts: the consumer there is
a line reader, and a pretty-printed multi-line object dropped into its input is
unparseable, so it would see the stream stop with garbage after the last good
record. Same fields, same code, same exit; only the framing follows the stream.
A negative --since is refused outright rather than serving `seq > -5` as if it
were a resume.

Activation is applied by the FACTORIES that build a store or a unit-of-work
provider, not by the commands that use one. It did not start there, and the
failures that got it here are the argument for the guard that now holds it:
first a process-global switch; then two root pre-run call sites, which covered
the CLI's own store and its proxied provider and missed `bd serve` (which
builds its own provider for a server-mode workspace), routed creates and
remote-cache hydration (which open a SECOND store for another workspace), the
pluggable backend registry arm, and the personal-migration planning store; then
a blanket exemption for bd doctor whose stated reason — "workspace repairs, not
bead mutations" — was FALSE for three of its repair handlers. Each ran with the
journal off while every command reported success, and an empty journal is
indistinguishable from a quiet one.

Those three now journal. StaleClosedIssues and PatrolPollution DELETE issues
and the two fresh-clone import paths CREATE them, so they open through an
activating factory of their own; a repair is the last place a silent divergence
is acceptable, because it runs unattended on a workspace someone is already
worried about. The policy moved to internal/eventsjournal for it: bd doctor's
fix package cannot import package main, and two copies of an activation rule is
how the rule stops being one rule. What remains exempt in doctor is named
handler by handler with a reason that can be checked against the code, rather
than inherited from a directory.

So TestEveryStoreConstructionActivatesTheEventsJournal enumerates every
construction of a store or provider across cmd/bd, bd doctor, its fix package
and the standalone embedded utility, and fails unless the constructing function
activates in its OWN body or carries a written exemption. Deliberately no
call-graph fixpoint: "the caller does it" is exactly the assumption that kept
being wrong. The factories use a deferred rewrite of their named results so the
open and its activation are one syntactic unit, which is what makes the check
local. Sites are keyed by file, so the CGO and non-CGO twins of a factory are
checked separately rather than one silently shadowing the other, and
constructors are matched through each file's IMPORT TABLE rather than by
package identifier — an aliased import would otherwise produce no site at all,
which is the worst thing a guard can do, because it reports success while
checking nothing. Its remaining honest limits (a constructor reached through a
method value, a package nobody added to the scan) are written down in the
guard rather than claimed away.

A cross-workspace open reads the TARGET workspace's own config.yaml, not the
launching one's: the journal records that workspace's mutations, so that
workspace decides whether they are recorded. An explicitly set
BD_EVENTS_JOURNAL outranks both — environment beats file here as everywhere
else in bd, and a routed write into several workspaces is exactly where an
operator reaches for it; a file that could veto it would make the variable a
suggestion, discovered later as an empty journal.

The three config keys join YamlOnlyKeys, which is the whole of review blocker 6.
They are read through viper during pre-run, before the store is open, so a
DB-backed write is silently unread — the GH#536 class that map exists to
prevent. TestEventsPruneHonorsRetainRowsFloorFromConfig enables the journal
through `bd config set` and then asserts records actually appear, so the
blocker cannot regress into a green suite.

The committed golden pins the record envelope external consumers parse,
including the comment op, and is built by marshaling real types.Issue /
EventDep / EventComment values through the same buildRecord path tail uses.
Four properties are guarded rather than assumed. No record may carry an inline
"dependencies" array. Every comment record's source must be one an emit site
can actually produce, and both must appear — the golden shipped for one
revision pinning "comment", a value invented for the fixture, which is worse
than no fixture because a golden's job is to be the thing consumers trust. And
the file must be reproducible: an issue snapshot carries wall-clock ride-alongs,
notably lease_expires_at / heartbeat_at, which a claim stamps from time.Now().
A fixture that reached for the clock would pass on the run that regenerated it
and fail on every run after, reading as flake rather than as the fixture bug it
is. Rather than normalize those fields away, the claimed fixture carries FIXED
lease values — so the golden pins the shape a consumer of a claimed bead really
sees — and a second test renders twice and requires byte equality.

The help text carries the contract a consumer has to know before it trusts a
cursor, because none of it is inferable from the records: the journal is
per-branch working-set state and per REPLICA, so `bd dolt pull` and the changes
a merge settles in are NOT journaled and a mirror must re-baseline after a sync;
each replica counts its own seq space, so a checkpoint taken against one is
meaningless against another; raw DML through `bd sql` bypasses the mutation seam;
store-open-time migrations and version reconciliation are unjournaled by design;
retention floors are not a consumer watermark; prune is manual and pairs with
`dolt gc`, since ordinary Dolt commits never collect dolt_ignored state. And the
two dependency asymmetries a naive consumer gets wrong: a dep_add is emitted for
an idempotent same-type re-add that only refreshes metadata (the audit table
dedupes that case, the journal does not — it is an upsert, not proof the edge is
new), and dep.metadata is the value being written on add but the raw stored
column read back on remove, so the two can differ byte for byte while meaning
the same thing.

Four end-to-end tests hold the activation paths, and each was verified by
removing the activation it covers: a proxied mutation reports "journaled 0
records"; `bd serve` against a server-mode workspace journals nothing for an
HTTP mutation; a routed create into a journal-enabled target records nothing;
and a bead-mutating `bd doctor --fix` deletes issues while journaling none of
them. The routed tests also pin the direction and the precedence — the
launching workspace, which enabled nothing, stays empty, and a target that
explicitly set the key to false is still overridden by the environment.

Ports cmd/bd/events.go + events_journal.go from 3bfed2431/0a3fe0f9b and the
golden from 3666e5026. Deviations: the reference's validateEventsJournalBackend
named a backend allowlist including a SQL family OSS main does not have, so the
capability check itself fails closed instead; its proxied prune used a
uow.RunInTx helper that does not exist here, replaced by RunTxEphemeral, which
states the dolt_ignored intent rather than relying on the commit path to demote
an empty DOLT_COMMIT; activation is factory-scoped rather than applied at the
reference's root pre-run call sites; and the golden's comment source is taken
from the engine's constants rather than restated.

Co-authored-by: CI Bot <ci@beads.test>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
2026-08-09 01:58:17 +00:00
.agent/workflows docs: replace bd sync with bd dolt push/pull in agent instructions (GH#2563) 2026-03-13 11:01:06 -07:00
.beads/formulas chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
.claude test: reconcile the sqlite-era tests the reapply left asserting live support 2026-07-18 02:43:57 +00:00
.claude-plugin chore: release v1.1.0 2026-07-03 22:34:03 -07:00
.devcontainer docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
.githooks Merge upstream/main into docs/mintlify-overhaul 2026-07-12 19:11:43 -07:00
.github test(storage): demote the duplicated keyset and max-rows backend tests 2026-08-07 20:32:19 +00:00
backend Merge pull request #5432 from gastownhall/conformance-update-accessor 2026-08-07 21:11:30 -07:00
beadserrors Move the namespace-neutral error vocabulary into its own leaf (#5395) 2026-08-07 04:32:06 -07:00
cmd/bd feat(events): bd events CLI, activation config, and the consumer golden (bd-opisf) 2026-08-09 01:58:17 +00:00
docs Merge main into fix/cross-repo-github-gates: adopt buildGateIssue refactor, keep repoMetadataForGate graft 2026-08-07 10:37:01 -07:00
engdocs Merge pull request #5431 from gastownhall/httpapi-wave-polish 2026-08-07 19:07:20 -07:00
examples docs(lint): align contributor guidance with CI (saa-90w) (#5317) 2026-08-07 05:37:12 -07:00
format feat: add public format package for issue rendering (#2871) 2026-04-02 19:33:53 -07:00
integrations build(deps): bump fastmcp (#5198) 2026-08-01 13:28:55 -07:00
internal feat(events): bd events CLI, activation config, and the consumer golden (bd-opisf) 2026-08-09 01:58:17 +00:00
issueops feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
memoryops Move the namespace-neutral error vocabulary into its own leaf (#5395) 2026-08-07 04:32:06 -07:00
npm-package docs: redirect legacy GitHub Pages site to Mintlify (#4759) 2026-07-13 14:19:13 -07:00
plugins/beads docs: caveat --parent label inheritance with size/effort labels (#4562) (#5123) 2026-07-31 01:44:50 -07:00
release-gates Fix: wisp delete never cascades to auxiliary tables (orphan row leak) (#5343) 2026-08-07 05:42:09 -07:00
schema feat: add public schema package re-exporting the migration API 2026-07-21 10:53:56 -07:00
scripts feat(events): clone-local events journal tables and the DML scanner (bd-opisf) 2026-08-09 01:58:17 +00:00
test feat(search): include closed issues by default (bd-t5yex) (#5392) 2026-08-07 00:35:50 -07:00
tests fix(show): expose guarded-write revision in JSON (#5353) 2026-08-05 19:51:49 -07:00
tools/docsmint test(docsmint): make missing staging path portable (#5076) 2026-07-28 09:01:56 -07:00
winget docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
.buildflags chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
.gitattributes fix(docs): pin generated CLI artifacts to LF (#4965) (#4966) 2026-07-23 18:24:58 -07:00
.gitignore refactor(cli): rename CPU profiling flag (#5126) 2026-07-28 22:17:13 -07:00
.golangci.yml Move the namespace-neutral error vocabulary into its own leaf (#5395) 2026-08-07 04:32:06 -07:00
.goreleaser.yml fix(release): branch install header for prerelease vs stable (#4530) 2026-07-01 22:59:50 -07:00
.pre-commit-config.yaml fix: detect Go version mismatch in pre-commit hook before golangci-lint panics (bd-66nc) 2026-03-02 18:50:29 -08:00
.test-skip fix: rewrite TestRepairMultiplePrefixes for Dolt rename semantics (bd-alk64) 2026-02-14 11:05:39 -08:00
AGENT_INSTRUCTIONS.md docs(lint): align contributor guidance with CI (saa-90w) (#5317) 2026-08-07 05:37:12 -07:00
AGENTS.md docs(lint): align contributor guidance with CI (saa-90w) (#5317) 2026-08-07 05:37:12 -07:00
ARTICLES.md fix(docs): remove stale --branch flag and SQLite refs from QUICKSTART (GH#2522) (#2525) 2026-03-11 12:54:30 -07:00
beads.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
beads_cgo.go feat(storage): add extension-safe backend registry seam (#4859) 2026-07-31 03:05:48 -07:00
beads_gated_test.go feat(workspacegate): shared physical-root resolver, beads.OpenGated, and CLI gate wiring (part 2) (#5093) 2026-07-31 01:41:20 -07:00
beads_nocgo.go feat(storage): add extension-safe backend registry seam (#4859) 2026-07-31 03:05:48 -07:00
beads_test.go feat(storage): refuse test DBs on production dolt servers (AD-01) (#3632) 2026-07-24 01:28:51 -07:00
BENCHMARKS.md test: add perf reference benchmarks (#4032) 2026-05-19 18:39:13 -07:00
build-docs.md fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
CHANGELOG.md docs(changelog): record the v0 write surface under Unreleased 2026-08-08 01:38:51 +00:00
claim.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
claim_roundtrip_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
claim_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
CLAUDE.md docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
codecov.yml test: improve coverage signal policy (#4219) 2026-05-27 22:05:14 -07:00
CONTRIBUTING.md docs(lint): align contributor guidance with CI (saa-90w) (#5317) 2026-08-07 05:37:12 -07:00
CONTRIBUTING_PR_GUIDELINES.md docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) (#3913) 2026-07-06 22:12:29 -07:00
default.nix chore(deps): bump the go-deps group across 1 directory with 11 updates (#5396) 2026-08-07 09:36:07 -07:00
errors_test.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
export_dependency_add_options_test.go feat: export DependencyAddOptions from the root package (#4870) 2026-07-17 20:34:32 -07:00
FEDERATION-SETUP.md chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
flake.lock flake.lock: Update (#4501) 2026-07-08 12:21:24 -07:00
flake.nix Guard and qualify historical upgrades to v1.2 (#4907) 2026-08-06 18:45:04 -07:00
go.mod chore(deps): bump the go-deps group across 1 directory with 11 updates (#5396) 2026-08-07 09:36:07 -07:00
go.sum chore(deps): bump the go-deps group across 1 directory with 11 updates (#5396) 2026-08-07 09:36:07 -07:00
install.ps1 docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
issue_lifecycle_external_test.go feat(storage): one guarded issue-lifecycle surface for the CLI and linked consumers (#5191) 2026-07-31 11:26:38 -07:00
issue_roles_external_test.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
issues.jsonl ci: add nix build check to catch vendorHash drift (GH#3298) (#3364) 2026-04-20 13:21:53 -07:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile Guard and qualify historical upgrades to v1.2 (#4907) 2026-08-06 18:45:04 -07:00
mint.sh chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
NEWSLETTER.md Retire legacy Homebrew tap publishing (#4478) 2026-06-22 19:26:46 -07:00
open_backend_selection_test.go feat(storage): add extension-safe backend registry seam (#4859) 2026-07-31 03:05:48 -07:00
open_nocgo_test.go :remove uneccessary locking 2026-05-01 17:46:37 -07:00
overlay.nix feat(nix): expose packages as an overlay for downstream override (#3910) 2026-07-06 22:39:37 -07:00
packages.nix feat(nix): expose packages as an overlay for downstream override (#3910) 2026-07-06 22:39:37 -07:00
PR_MAINTAINER_GUIDELINES.md docs(maintainer): prior-art pass is part of every review; rebases are maintainer work (#5094) 2026-07-26 21:40:34 -07:00
PROPOSAL-cas-conditional-update.md fix(claim): verify claim-family writes by re-read under a degraded server (bd-zccb9) (#5006) 2026-07-24 07:21:24 -07:00
PROPOSAL-pluggable-storage-backends.md Reapply "Simplify the supported backends: roll back the direct PostgreSQL and MySQL adapters" (#4857) 2026-07-18 02:43:56 +00:00
PROPOSAL-pull-config-wedge.md fix(dolt): pre-pull commit must include config (kv.memory.* pull-wedge) (#4412) 2026-06-19 21:31:33 -07:00
query_interfaces_cgo_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
query_interfaces_test.go feat(storage): events + dependents reads, batched blocked, public claim surface (#4926) 2026-07-22 07:41:47 -07:00
README.md docs: schema-version guard in README and CHANGELOG (be-x0rl6) (#4161) 2026-07-23 19:13:38 -07:00
RELEASING.md docs(release): make the CLI docs pin bump an explicit release step (wy-gx5rj) 2026-07-25 16:35:05 -07:00
renovate.json chore: harden release and dependency security 2026-04-28 08:45:22 +00:00
SECURITY.md docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
THIRD_PARTY_LICENSES revert: restore embedded Dolt mode (was only supposed to be removed from Gas Town) 2026-02-07 21:21:24 -08:00

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI

Docs: https://beads.gascity.com/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

flowchart LR
    create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
    depgraph --> ready["bd ready<br/>claimable work"]
    ready --> claim["bd update --claim<br/>agent takes it"]
    claim --> close["bd close<br/>work done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features

  • Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  • Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
  • Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
  • Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
  • Graph Links: relates-to, duplicates, supersedes, and replies-to for knowledge graphs.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
bd update <id> --claim Atomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent> Link tasks (blocks, related, parent-child).
bd show <id> View task details and audit trail.
bd prime Print agent workflow context and persistent memories.
bd remember "insight" Store project memory that bd prime injects later.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

  • bd-a3f8 (Epic)
  • bd-a3f8.1 (Task)
  • bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

  • Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
  • Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install, and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate and bd dolt push; other clones install the new binary and run bd bootstrap. See the full upgrade guide or docs/getting-started/installation.md.

Security And Verification

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes:

  • Embedded (default) — bd init. Dolt runs in-process, data lives in .beads/embeddeddolt/, single writer. Recommended for most users.
  • Server — bd init --server. Connects to an external dolt sql-server for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against refs/dolt/data on your git remote; .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup. Back up and migrate between modes with bd backup; reclaim space with bd prune / bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.

Schema Version Guard

bd checks the database schema version at open time. If the database has been migrated by a newer binary and an older binary tries to open it, bd exits with an actionable error rather than issuing queries that fail with cryptic SQL errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses the guard with a warning on stderr. Use this only if you know the forward migrations are additive and safe for your specific workload.

🌐 Community Tools

See docs/community-tools.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

  • Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
  • Monorepos — point BEADS_DIR at a specific subdirectory
  • CI/CD — isolated task tracking without repo-level side effects
  • Evaluation/testing — ephemeral databases in /tmp

📝 Documentation