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
Stephanie Jarmak 559b5de1e2
fix(memory): preserve presence for empty values (#5964)
* fix(memory): preserve presence for empty values (#5963)

Recall and Forget now distinguish an existing empty memory row from an absent key across direct, embedded, and UOW storage paths.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of sjarmak

* fix(memory): make bd recall report presence from row existence

printRecallResult (and the recallCmd caller) derived "found" from
value != "", so a memory stored as the empty string still printed
"No memory with key" and exited 1 even though the role's
RecallResult.Found was true and bd forget would delete the row.
Thread result.Found through instead: an empty-valued memory now
recalls cleanly (exit 0, empty value; JSON reports found: true), and
only an absent key is a miss.

Addresses maintainer review on #5964 (fixes #5963).

* test(httpapi): pin GET /v0/beads/memories/{key} as 200 for an empty value

TestGetMemoryAnswersAMissWithA404 pinned a RecallResult{Value: ""}
case (Found defaulting to its zero value, false) as a 404, a shape no
backend can produce since Found now comes from row existence rather
than value truthiness. Move that case into its own
TestGetMemoryAnswersAnEmptyValueWith200, which recalls Found: true
and asserts a 200 with an empty value. Also updates the handler's
doc comment, which still described the retired 404-on-empty
behavior.

Addresses maintainer review on #5964 (fixes #5963).

* docs(httpapi): fix openapi spec to say memory presence is row existence

The published spec still said an empty-valued memory is a 404 on
GET /v0/beads/memories/{key} and DELETE /v0/beads/memories/{key},
contradicting the role's RecallResult.Found (row existence). Rewrite
the operation descriptions, both 404 response bodies, Memory.value
and RememberedMemory.replaced to say presence is row existence
everywhere: an empty-string memory is a 200 (or is removed by
forget) with an empty value, matching what GET /v0/beads/memories
already enumerated. Regenerate types.gen.go via `make api-gen` so
the generated doc comments match.

Addresses maintainer review on #5964 (fixes #5963).

* docs(changelog): note the empty-valued memory presence fix

Add an Unreleased/Fixed entry for #5964 (fixes #5963): bd recall,
bd forget and GET /v0/beads/memories/{key} now treat an empty-valued
memory as present everywhere, instead of only on GET
/v0/beads/memories.

* fix(memory): make bd remember <bare-key> recall an empty-valued memory

rememberBareKeyPath decided presence from existing != "", so a bare slug
naming a memory stored as the empty string was refused as "no memory
named" instead of recalled. It now takes the role's Found, matching
printRecallResult, bd forget and the HTTP door.

* test(memory): pin empty-value presence through the real commands

TestPrintRecallResult and TestRememberBareKeyPath call the helpers directly,
so a RunE that went back to deciding presence from value != "" would leave
them green. TestEmbeddedMemory/empty_valued_memory_is_present empties a
memory row beneath bd and runs bd recall, bd remember <bare-key> and
bd forget against it, checking first that bd no longer sees the placeholder.

Two comments in problem.go and one in memories_test.go still said an
empty-valued memory is a 404. The CHANGELOG line now says a key with no row
is a miss, since a forgotten key was once stored.

* build(bazel): add the memoryops dep to the bd_test go_test (make bazel-sync)

memory_embedded_test.go now imports internal/storage/memoryops directly
(storagememoryops.StorageKey, to overwrite a memory row out of band), so
gazelle emits //internal/storage/memoryops on bd_test. cmd/bd/BUILD.bazel
landed on main after this PR branched, so the PR could not carry the dep;
without it, bazel.yml's "BUILD files in sync" step fails in the required
bazel-test lane. Generated by `make bazel-sync`.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(memory): maintainer fixup — adoption review nits

Maintainer fixup for the adopt-pr iteration-1 review of #5964. Both review
lanes approved and the quality scorecard approved at 981; these are its four
non-gating nits, each confined to lines this PR already adds.

- internal/httpapi: TestForgetMemoryOfAnEmptyValuedKeyIs200 pins the DELETE
  door's empty-value 200 the way TestGetMemoryAnswersAnEmptyValueWith200
  pins the read. Guarding the handler's 404 on Value == "" reddens exactly
  this test and nothing else.
- CHANGELOG: the bullet names DELETE /v0/beads/memories/{key} beside GET,
  whose answer changed the same way (404 with the row left standing -> 200
  with the row removed).
- uow: the two new GetAllConfig presence probes in Recall and Forget say why
  they read the whole table, by pointing at Remember's rationale.
- conformance: RunMemoriesEmptyRowIsPresentUntilForgotten runs its
  no-history-on-retry leg last and SKIPs it with a reason when a fixture has
  no CountHistory, as the MemoriesFixture doc promises, instead of passing
  quietly. All three in-tree fixtures wire the hook, so every in-tree run
  is unchanged (19/19 on dolt, embeddeddolt and uow, 0 SKIP).

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(httpclient): report an empty-valued memory as present (base-refresh repair)

Maintainer repair from refreshing #5964 onto main b630f96f5b. Main's #7247
added the HTTP client store (internal/httpclient) after this PR branched,
and its memory role and served conformance leg still treated a memory
stored as the empty string as absent:

- Recall set Found from Value != "".
- The RecallMemory doc said an empty-valued row was a 404.
- TestServedMemoriesRecallConflatesStoredEmptyWithAbsent called
  conformance.RunMemoriesRecallConflatesStoredEmptyWithAbsent, which this
  PR deletes.

The rebase applied cleanly, but the merged tree did not compile.

- internal/httpclient/memories.go: Recall reports Found true on any 200.
  With this PR the wire returns a 404 only for a key with no row; an
  empty-valued row comes back as a 200 with an empty value. Setting Found
  from Value would hide that row again on the HTTP backend. Forget already
  reported Found true on a 200.
- internal/httpclient/wire/writes.go: the RecallMemory doc now says the
  same.
- internal/httpclient/served_memories_deps_test.go: the hm10 served case
  now runs RunMemoriesEmptyRowIsPresentUntilForgotten, the contract case
  this PR adds in place of the one it deletes.

With BEADS_TEST_EMBEDDED_DOLT=1 the served memory tests pass with 0 SKIP.
Reverting the Recall line makes hm10 fail with
`Recall("hm10-stored-empty") = value "" found false, want value "" found
true`.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: sjarmak <t@t.co>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 19:28:54 +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(ci-policy): close review leftovers from #7485/#7486 (#7491) 2026-10-11 01:22:48 +00:00
backend fix(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +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(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +00:00
docs fix(schema,uow): route the proxied data-behind open to the #6575 stop (port of #6695 to main) (#7481) 2026-10-11 00:23:25 +00:00
engdocs test(backend/http/corpus): served MC command corpus against the reference server profile (S23) (#7483) 2026-10-11 05:34:51 +00:00
examples fix(examples): bump grpc to 1.83.2 and thrift to 0.24.0 in example modules (#7467) 2026-10-10 12:15:33 +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(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +00:00
issueops fix(httpclient): unlimited ready/query/list reads over http, client-capped (S15) (#7497) 2026-10-12 09:02:22 +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 test(backend/http/corpus): served MC command corpus against the reference server profile (S23) (#7483) 2026-10-11 05:34:51 +00:00
test feat(backend/http): public HTTP backend door, OSS registration, and bd connect (S6) (#7288) 2026-10-10 07:19:18 +00:00
tests fix(issueops): enforce the close guards on every close leg (#7425) 2026-10-09 18:30:42 +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 ci: F5 S2 Variant A — nogo ownership for the integration configuration group (#7486) 2026-10-10 23:19:16 +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: F5 S2 Variant A — nogo ownership for the integration configuration group (#7486) 2026-10-10 23:19:16 +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 ci(bazel): nogo replaces go vet and golangci-lint (ga-96smfk.18) (#7341) 2026-10-07 05:17:22 +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(memory): preserve presence for empty values (#5964) 2026-10-12 19:28:54 +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 fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +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 flake.lock: Update (#4501) 2026-07-08 12:21:24 -07:00
flake.nix ci(bazel): run the hook-timeout-backends check under Bazel; test-nix stops running tests (#7357) 2026-10-07 11:05:39 +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 fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +00:00
go.sum fix(deps): bump grpc to 1.83.2 and thrift to 0.24.0 (#7495) 2026-10-11 09:58:58 +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(roles): LeaseReclaimer role, POST issues:reclaim, and bd reclaim on both routes (S9) (#7412) 2026-10-09 14:56:32 +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(http): list/show counts/dep tree/ping over http, the advertised external-dependency policy, one-lookup not-found (S6b/S6c/S6d) (#7471) 2026-10-10 18:11:56 +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 Four-leg no-op conformance case for #5898: duplicate dep add and absent dep remove mint no version on any leg (#6650) 2026-09-26 14:48:30 -07: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.

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