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
Eddie the Engineer 2068dbee97 fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071)
Review fixes for #7646, iterations 1, 2 and 3. This replaces the
unpushed iteration-1 commit 89f67d6bbe. The nine contributor commits are
rebased onto main at ce70b261c5, and the migration moves from 0070 to
0071 because #6943 landed its participation_generation migration at 0070
first. With two 0070s, the schema test package does not compile, the
hygiene check fails, and every bd command that opens a store panics with
"schema: duplicate migration version 70".

The Dolt 2.4.1 driver stores the created_at DESC that migration 0010
declares on idx_comp_snap_issue as descending (dolthub/dolt#11746), so
every database it creates was unreadable by Dolt older than 2.3.3:
released bd (v1.3.x links driver v2.2.0) failed on open with "table has
unknown fields", which BD_IGNORE_SCHEMA_SKEW=1 does not get past.
Migration 0071 adds idx_comp_snap_issue_asc (issue_id,
compaction_level, created_at) and then drops idx_comp_snap_issue, each
step guarded on INFORMATION_SCHEMA.STATISTICS the way 0042 is.
fk_comp_snap_issue keeps ON DELETE/ON UPDATE CASCADE. The descending
order never served a query.

Measured 2026-10-18 on a database bd init built from this tree
(schema_migrations at 71, participation_generation present, no
descending column at the root): dolt 2.1.8 and 2.2.0 read, write, push,
clone and pull it, and the installed v1.3.0 bd (driver v2.2.0) stops at
its structured "database is at v71, binary knows up to v69" refusal,
which BD_IGNORE_SCHEMA_SKEW=1 gets past. With 0071 reverted,
information_schema queries and writes fail with "table has unknown
fields" (push and clone still copy the chunks), on 2.1.8 an UPDATE or
DELETE on issues reports a fk_comp_snap_issue violation, 2.2.0's pull
fails, and the v1.3.0 bd fails with the engine error that
BD_IGNORE_SCHEMA_SKEW=1 does not get past.

History keeps the descending column: bd init commits each migration
separately, so the commits from before 0071 still hold it. On 2.1.8 and
2.2.0, reading compaction_snapshots at one of them (AS OF,
dolt_history_compaction_snapshots, dolt_diff_compaction_snapshots)
fails, and so does any dolt diff with one as an endpoint, even a diff
limited to issues. issues AS OF, dolt_history_issues and
dolt_diff_issues work. The up.sql header, the CHANGELOG and
docs/architecture/dolt.md say so.

Migrations take slots in landing order, and versions must stay
gap-free (TestAllMigrationsSQLAppliesThroughDoltCLIAndRecordsLatestVersion).
#6661 also numbers a migration 0071; whichever lands second renumbers.

Tests: TestLatestVersionIncludesMigration0071 is the slot pin, and
main's TestLatestVersionIncludesMigration0070 is deleted, as each
earlier pin was when the next migration landed. A pure-Go test checks
the frozen text and the down file, and a dolt CLI test checks the
bundle leaves no descending column. An embedded test covers the upgrade
from v69 through 0070 and 0071, a replay, the foreign key's cascade,
resume after the add, a store without the table, and a fresh store.
cli_prepared_ddl.go's inventory justifies the prepared ADD/DROP INDEX,
measured to execute through the CLI batch path on 2.1.8 and 2.4.1.

The example modules replace github.com/steveyegge/beads with the repo
root, so they have to follow its dependency bump. On the iteration-2
head 72f5a6794e, scripts/build-examples.sh failed both with "updates
to go.mod needed". go mod tidy in examples/library-usage and
examples/bd-example-extension-go moves them to the root's versions
(driver v2.4.1, dolthub/file-locks v0.1.2 and the go-deps group).
Every requirement they share with the root go.mod now matches it
except golang.org/x/exp, which both already pinned to a newer version
on main. The script now prints "2 example module(s) type-check
cleanly".

Minor and nit findings:
- The proxied-server old-version warning scopes each reason to the
  releases it covers, without naming a schema version: the
  CALL DOLT_RESET('--hard') regression measured on 2.3.0 and 2.3.1
  (2.3.2 through 2.4.0 unmeasured, 2.4.1 measured clean), the join
  mis-plan before 2.4.0, and "table has unknown fields" before 2.3.3.
  A 2.4.0 user now reads why 2.4.1 is still recommended.
  TestWarningMessage pins all three; dropping the DOLT_RESET clause
  fails it.
- scripts/ci/install-dolt.sh no longer says 2.4.1-engine storage is
  unwritable by 2.2.0. It names the join bug and the split between the
  current root, which 2.1.8 and 2.2.0 read and write, and the commits
  from before 0071.
- scripts/test-git-remote.sh keeps its dolt >= 2.2.0 floor, backed by
  a 2.2.0 run of its write, push, clone and pull steps.
- The dated cross-version measurements live in docs/architecture/dolt.md;
  policy.go and troubleshooting.md point there.
- The CHANGELOG scopes the fk_comp_snap_issue violation to 2.1.8.
- The localdoltserver port comment covers 2.4.1 as well as 2.2.0; both
  print "Port N already in use." on a held port (measured).
- TestEmbeddedFirstMintOnEmptyHistoryIsRevisionOne pins that revisions
  count per issue.
- docs/architecture/dolt.md says 2.4.1 is the only release after 2.3.1
  measured for the DOLT_RESET regression and that 2.3.2, 2.3.3 and
  2.4.0 have not been. It had said no release after 2.3.1 was, right
  under the 2.4.1 0 / 250 row.
- cli_migrations.go puts the parity oracle's green run against the
  then-pinned 2.2.0 sql-server in the past tense. Probed 2026-10-18, a
  prepared ADD COLUMN vanishes on the 2.2.0 CLI and lands on 2.4.1, so
  on the 2.4.1 pin the oracle cannot catch a dropped override; the
  comment names the two binary-free tests that still can.

Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 16:25:40 +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 release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -07:00
.claude docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
.claude-plugin release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -07:00
.devcontainer docs: move internal/maintainer docs from docs/ to engdocs/ 2026-07-12 10:37:07 -07:00
.githooks fix(hooks): key the push-time suite on the remote ref, never on the local ref's shape (#7352) 2026-10-08 07:49:57 +00:00
.github fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +00:00
backend storage: add participation_generation (migration 0070) and the versioned-history write fence (#6943) 2026-10-18 13:10:57 +00:00
beadserrors ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
cmd/bd fix(bootstrap): cut the host part before stripping userinfo (mc-gcmer) (#7616) 2026-10-17 18:07:50 +00:00
docs fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +00:00
engdocs feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
examples fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +00:00
format ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
integrations fix(beads-mcp): bump pyjwt to 2.15.1 and urllib3 to 2.8.0 for security advisories (#7466) 2026-10-10 12:36:14 +00:00
internal fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +00:00
issueops feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00:00
journalops ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
memoryops fix(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +00:00
npm-package release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -07:00
platforms build(rbe): re-pin worker-env to gascity's go1.26.9 worker host (#7411) 2026-10-09 07:38:56 +00:00
plugins/beads ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
release-gates fix(metrics): stop failing the reap test on a transient zombie (#6262) 2026-09-08 18:16:35 -07:00
schema ci(bazel): split //scripts:scripts_test by what it reads; partition //:repo_files (#7414) 2026-10-09 05:13:07 +00:00
scripts fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +00:00
test fix(http): bd promote over http through issueops.Promote and issues.update.persistence (S21b) (#7554) 2026-10-14 05:51:53 +00:00
tests ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
third_party ci(bazel): fetch pinned Ubuntu debs in parallel from a gascity mirror first (#7434) 2026-10-09 17:47:17 +00:00
tools build(dolt): raise the Dolt CLI, container and Bazel pins to 2.4.1 2026-10-18 14:05:10 +00:00
winget fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
.bazelignore ci(bazel): run pr.yml's repository guards as Bazel tests (#7329) 2026-10-07 00:59:18 +00:00
.bazelrc ci(bazel): dolt-int gates server-storage + cmd-dolt in mode remote (item 5 A2) (#7535) 2026-10-13 09:17:54 +00:00
.bazelversion ci(bazel): Bazel 9.3.0 (prerequisite for the remote repo contents cache) (#7439) 2026-10-09 21:03:41 +00:00
.buildflags chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
.gitattributes build: make repository text EOL deterministic (#5319) 2026-08-10 20:48:09 -07:00
.gitignore build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
.golangci.yml fix(http): bd gate check over HTTP through issueops.ListGates (#7578) 2026-10-16 09:20:24 +00: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 ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
.test-skip fix: rewrite TestRepairMultiplePrefixes for Dolt rename semantics (bd-alk64) 2026-02-14 11:05:39 -08:00
AGENT_INSTRUCTIONS.md docs(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
AGENTS.md docs(bazel): make bazel test the primary build and test path (ga-96smfk.23) (#7348) 2026-10-07 07:46:02 +00: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(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
beads_cgo.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -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(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -07:00
beads_test.go test(testutil): opt-in local dolt sql-server backend for Dolt-backed tests (#6891) 2026-09-28 04:06:49 -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
BUILD.bazel test(backend/http/corpus): served MC command corpus against the reference server profile (S23) (#7483) 2026-10-11 05:34:51 +00:00
CHANGELOG.md fix(schema): replace compaction_snapshots' descending index with an ascending twin (0071) 2026-10-18 16:25:40 +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(agents): contributor-only agent instructions and documented-issue intake (#7223) 2026-10-05 08:43:53 +00:00
codecov.yml test: improve coverage signal policy (#4219) 2026-05-27 22:05:14 -07:00
CONTRIBUTING.md ci(bazel): run the hook-timeout-backends check under Bazel; test-nix stops running tests (#7357) 2026-10-07 11:05:39 +00: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 build(deps): bump dolthub/file-locks to v0.1.2 for BSD builds 2026-10-18 14:05:10 +00: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 build(nix): move the flake to nixos-26.05 for go 1.26.5+ 2026-10-18 14:05:10 +00:00
flake.nix build(nix): move the flake to nixos-26.05 for go 1.26.5+ 2026-10-18 14:05:10 +00:00
gazelle.go.work ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +00:00
go.mod build(deps): bump dolthub/file-locks to v0.1.2 for BSD builds 2026-10-18 14:05:10 +00:00
go.sum build(deps): bump dolthub/file-locks to v0.1.2 for BSD builds 2026-10-18 14:05:10 +00: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 feat(http): bd blocked over bd serve (blocked.list), plus bd blocked --flags [--raw] (#7649) 2026-10-17 12:29:13 +00: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 fix(bazel): one nogo-validating lane per race configuration (F5 S1) (#7479) 2026-10-10 18:05:17 +00:00
mint.sh chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
MODULE.bazel fix(build): pair Darwin SDKs with the native Apple linker (#7460) 2026-10-11 03:51:25 +00:00
MODULE.bazel.lock ci(bazel): Bazel 9.3.0 (prerequisite for the remote repo contents cache) (#7439) 2026-10-09 21:03:41 +00:00
NEWSLETTER.md Retire legacy Homebrew tap publishing (#4478) 2026-06-22 19:26:46 -07:00
open_backend_selection_test.go feat(backends): registry Remote + OpenWith options; beads.OpenBestAvailableWith for embedders (#7188) 2026-10-04 09:34:36 -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 feat(list): bd list's remaining filters over http behind issues.list.filters (#7647) 2026-10-17 11:21:18 +00:00
RELEASING.md ci(bazel): retire main.yml's Linux jobs, nightly's go test jobs and ci-measurements (#7354) 2026-10-07 10:06:59 +00:00
renovate.json chore: harden release and dependency security 2026-04-28 08:45:22 +00:00
ROADMAP.md docs(contributing): recommend issues when they add context instead of requiring one per PR (#7323) 2026-10-06 23:29:09 +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
VERSIONED-BEADS-WRITE-PATHS.md storage: add participation_generation (migration 0070) and the versioned-history write fence (#6943) 2026-10-18 13:10:57 +00: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 the project Claude Code, Codex, and Cursor 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 durable project facts; keep per-operator preferences in your harness's own memory.
- 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 schema 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.

🔌 HTTP Backend (experimental)

A workspace can also talk to a remote bd serve over HTTP instead of opening a local Dolt database — useful for a thin client against a shared server, or for embedding beads in another program as a library.

# Point this workspace at a server (verifies the server first; writes nothing on failure)
bd connect https://bd.example.com --expect-project-id my-project

# The everyday commands work the same way: create, show, list, update, close,
# dependencies (including `bd dep tree`), comments, ready/count queries, and
# batch apply all round-trip over the wire with the same semantics as a local
# database. So does `bd ready --claim`, except against an older server or while
# any issue holds an unsatisfied external ref: then it lists and claims in two
# steps rather than one transaction (ledger row L14, linked below).
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd close bd-a1b2 "Fixed"

# Loopback needs no TLS
bd connect http://127.0.0.1:8080

# Forget the server and restore this workspace's previous backend selection
bd connect --clear

HTTP mode is not a byte-for-byte mirror of local mode, though: some operations are knowingly refused (the wire has no way to express them) or degrade to a different-but-not-misreadable behavior (for example, a few unbounded listing shapes lose single-query snapshot isolation and instead walk the server page by page). Every one of these is a deliberate, tested row, never a silent gap — see engdocs/design/http-divergence-ledger.md for the full, generated list of what differs and why before depending on an HTTP-backed workspace for a workflow you haven't checked against it. One refusal to know up front: bd close --claim-next closes nothing over HTTP, because the wire's batch close cannot carry the claim. Close without it, then run bd ready --claim.

Cross-repo dependencies keep their policy over HTTP. The client resolves each external: reference against its own external_projects configuration. bd dep tree shows the reference as a leaf, and while it is unsatisfied the issue stays out of bd ready and bd ready --claim, and bd close refuses it without --force. A server that advertises enforcing that policy itself is trusted to do so instead.

Three CLI-level differences are worth knowing up front:

  • IDs resolve exactly: an abbreviated id is not expanded (the wire has no substring search), and a missing id is reported as not found after one lookup.
  • bd update -s closed does not record closed_by_session (from --session or CLAUDE_SESSION_ID), because the wire's update cannot carry it; the close itself happens as usual. bd close does record the session. bd reopen's history entry carries the server's own label.
  • Contributor auto-routing (routing.* settings) is read from local config.yaml / environment only, never from the server's settings: its targets are local paths.

bd connect writes two things on success: .beads/metadata.json gets "backend": "http", and a per-user, never-git-tracked sidecar (.beads/http_target.json) records the server URL and pinned project id. It never writes a credential to disk. A bearer credential, if the server requires one, comes from BEADS_HTTP_TOKEN=host[:port]=<token>, then BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command> (a helper that prints a token), then the credentials file, then no credential at all. Both variables must name the server they are for (a pattern without a port matches that host on any port); a bare value is refused, because it would be sent to whatever server the workspace's http_target.json names. Connecting to a non-loopback server over plain http:// is refused by default (a bearer credential would cross the network unencrypted) — pass --allow-plaintext to override, or use https://. Switching a workspace that already selects a different backend needs --force.

Each read (a GET, or the POST batch get) gives its first attempt 15s, from when the request is sent, to get the server's response headers (BEADS_HTTP_RESPONSE_HEADER_TIMEOUT: a duration such as 30s, a number of seconds, or off). A read whose headers do not arrive in time, or whose connection is reset, is retried once on another connection, and each retry is logged to stderr with its count. The retry has no header timer, but it runs on what is left of the 60s bound on the whole request, counted from when the first attempt was sent: a slow but healthy read still finishes if the retry's headers and body together fit in that remainder (about 45s after a header timeout), and one that needs longer now fails at 60s. The header timer never cuts off a body that is still streaming; the 60s bound still does. The events:watch stream's connect gets neither the header timer nor the retry. On Windows a reset connection is retried only when it surfaces as an early EOF, because the check matches the Unix reset error (ECONNRESET), which a Windows reset (WSAECONNRESET) is not. A write gets no header timer (the server answers a write only after it commits, so a large one can be slow and healthy) and is never retried; if the 60s bound expires after it was sent but before its headers, it fails with an error naming the server's host, because it may or may not have been applied. A batch apply of more than 100 items (a large bd create --graph plan, say) gets 6 minutes instead of 60s, because bd serve gives such a request its --large-apply-ceiling (5 minutes by default) and finishes it even after the client has given up. A server whose ceiling is raised past about 5m15s can still outlast the client. A dial or TLS timeout stays a plain connection error, since the server never saw the request. off turns off only the header timer: a reset read is still retried, and a write's timeout is still reported as above.

bd search, bd show --current and bd recompute-blocked work over HTTP too, each in its own way. bd search asks the server's listing with its text (q, behind the issues.list.search capability) and refuses before dialing against a server that does not advertise it. bd list --no-assignee, --title and --id likewise ride the listing's no_assignee, title and repeatable id, each behind its own capability (issues.list.noAssignee, issues.list.title, issues.list.ids), and the rest of bd list's filters (--updated-*, --closed-*, --defer-*, --due-*, --priority*, the text and external-ref matches, --spec, --label-pattern/--label-regex, --exclude-type, --no-parent, --no-labels, --empty-description, --pinned/--no-pinned, --deferred, --overdue, --mol-type, --wisp-type) ride it behind one capability, issues.list.filters. Time bounds are resolved on the client as they are locally; --overdue compares against the server's clock. The default --parent tree view does not carry those filters yet and refuses one rather than drop it; --flat or --json applies them to the parent's direct children (not its whole subtree). bd show --current finds the actor's in-progress or hooked issue through the server's boolean query. bd recompute-blocked is a no-op that exits 0: the server maintains is_blocked on every write, and repairing a stale flag is done in the server's own workspace (--json reports {"rows_corrected": 0, "maintained_by": "server"}).

An embedding program that links beads as a library rather than running cmd/bd registers this backend itself through the public backend/http package (bdhttp.Register), and can open a workspace with a credential scoped to one caller via beads.OpenBestAvailableWith — see that package's doc comment for the multi-tenant case. This surface is EXPERIMENTAL: pin an exact beads version.

🌐 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