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
Julian Knutsen 54c1300a18
fix(config): dotted keys round-trip through SetYamlConfigInDir/UnsetYamlConfig (bd-zj95, 1.3.1) (#6574)
* fix(config): make a dotted key round-trip through SetYamlConfigInDir (bd-zj95)

SetYamlConfigInDir writes dotted keys; GetStringFromDir reads them by splitting
on the dot and walking nested mappings; UnsetYamlConfig removes them. Those are
three directions of ONE round-trip property, and set/get was broken in two ways,
both reachable from ordinary files:

  - An empty or comment-only config.yaml has no mapping node, so the nested
    writer declined and the caller appended a literal 'dolt.host: ...' line — a
    key whose NAME contains a dot. Nothing that splits on the dot can ever find
    it.
  - A file that already carried such a flat key had it updated in place, which
    preserved the unreadable shape forever.

So a caller could write a value and immediately be unable to read it back. Two
consumers found it the hard way: bd's ownership handoff, whose commit write-set
refused itself on dolt.auto-start, and a Gas City managed city, whose
.beads/config.yaml is entirely flat dotted keys.

Six shipped call sites write a dotted key through this path, and every one of
them is a write into a .beads/config.yaml that may be empty or comment-only —
exactly the shape that produced the unreadable spelling:

  cmd/bd/bootstrap.go:1108         sync.remote
  cmd/bd/dolt.go:481               sync.remote
  cmd/bd/init.go:3386, :3394       sync.remote
  cmd/bd/migrate_dolt_mode.go:810  dolt.shared-server
  cmd/bd/migrate_dolt_mode.go:1168 dolt.shared-server

An empty document now gets a mapping made for it, and a flat key of the name
being written is migrated to the nested form rather than updated in place. Only
the key being written is touched: a dotted key this call does not own belongs to
someone else and is left exactly as they wrote it.

Table test over nine file shapes — absent, empty, comment-only, flat, flat
commented, existing section, unrelated nested, unrelated flat, and mixed — each
asserting both that every key reads back and that no unreadable flat spelling
survives.

(cherry picked from commit cbe9bd6ca03416a76441e560bdec9fa67add99c5)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(config): unset a dotted key in the shape the writer produces

Writing a dotted key nested and then being unable to unset it is the same
round-trip break in the other direction. Set, get and unset are three directions
of ONE property, and all three have to agree on the shape: UnsetYamlConfig
comments out the line matching the key, and its pattern only ever matched a FLAT
'sync.remote:' line. Once the writer nests, an unset silently does nothing and
the value stays live — for sync.remote that means bd keeps a remote the operator
asked it to forget.

commentOutYamlKey now walks the nesting, tracking indentation per segment so a
key is commented only when it sits under its OWN parents rather than under some
other section sharing a leaf name. The flat spelling is still handled, because
files written by older bds carry it.

This is what closes the loop for the shipped unset paths — cmd/bd/config.go:578
('bd config unset'), cmd/bd/dolt.go:1761 and
cmd/bd/dolt_remote_proxied_server.go:34 — against the six writers the previous
commit nests: sync.remote at cmd/bd/bootstrap.go:1108, cmd/bd/dolt.go:481 and
cmd/bd/init.go:3386/:3394, and dolt.shared-server at
cmd/bd/migrate_dolt_mode.go:810/:1168.

TestFinalizeSyncedBootstrapWritesConfigFiles moves with it. It required a
literal 'sync.remote: ' line — a key whose name contains a dot, the one shape
GetStringFromDir and viper can never find, because both split on the dot and
walk nested mappings. That assertion passed for exactly as long as the value was
unreadable and failed the moment it became readable, so it now asserts what
bootstrap actually owes its caller: a remote that reads back.

(cherry picked from the internal/config half of commit
7f1ec4799a3e8af0a89b8f97c28ec30082fedbb7)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* test(cmd/bd): assert the sync.remote round trip, not a YAML spelling

Six cmd/bd test sites baked the flat spelling. They passed BECAUSE the bug was
present, and that is the part worth recording.

Viper finds a literal dotted key as well as a nested one; GetStringFromDir does
not, because it splits on the dot and walks mappings. So these tests exercised
config.yaml through ONE reader while the value was invisible to the other. They
were green for exactly as long as the value was unreadable, and
TestFinalizeSyncedBootstrapWritesConfigFiles failed on macOS and Linux CI the
moment it became readable. A test that only passes while a bug is live does not
merely fail to catch it — it defends it.

  bootstrap_guard_test.go:84        seed
  bootstrap_test.go:358, :410       seed
  bootstrap_test.go:1330            assert (accepted 'sync.remote: ' OR
                                    'sync-remote: ', neither readable)
  dolt_worktree_remote_test.go:55   assert
  init_remote_test.go:128           seed

All six now assert the round trip through GetStringFromDir, or the caller's own
observable, rather than any YAML text — flat or nested. Asserting the nested
spelling instead would have been the same mistake facing the other way.

The three seeds go through config.SetYamlConfigInDir, the real writer, via a
shared seedSyncRemote helper that asserts the read-back. A fixture can no longer
hand bd a config.yaml that bd itself would never have written.

These are the tests standing over the shipped writers this series fixes:
sync.remote at cmd/bd/bootstrap.go:1108, cmd/bd/dolt.go:481 and
cmd/bd/init.go:3386/:3394, and dolt.shared-server at
cmd/bd/migrate_dolt_mode.go:810/:1168.

(cherry picked from commit b0df00b59d2d68ee5fee313c05dc2300ad66fcef)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(config): close the dotted-key round trip the rest of the way

Review of the first three commits found the round trip still open in two
places, both reachable from ordinary files.

An empty or comment-only config.yaml parses to no YAML nodes at all, and
yaml.v3 keeps no trace of its text either — not even the comments. The
writer fabricated a mapping for that case and marshalled it, so the file
it wrote back was the new key and nothing else. `bd init` writes a
template that is comments and nothing else and then persists sync.remote
into it, so every remote-connected init shipped a config.yaml with its
whole documentation deleted. config.yaml is git-tracked: the operator
sees that as a committed diff they did not make. Append the rendered key
to the existing text instead, so nothing already in the file is parsed,
re-emitted or reformatted, and it survives byte for byte.

An unset comments the leaf out and leaves the section holding nothing —
`sync:` and no more. A null is not a mapping, so the next set refused it,
fell through to the flat writer, and put a literal `sync.remote:` back
into the file: the unreadable shape, re-created one command after being
fixed, with bd reporting success while GetStringFromDir saw nothing. A
section with no value under it has nothing to lose, so treat it as the
empty mapping it looks like.

Two shapes that are genuinely unwritable now say so instead of writing
the flat key and claiming success: a parent that already holds a value
(`sync: enabled`), and a file whose top level is not a mapping. Both
returned nil and produced a value no reader could see.

Unset also matched lines inside literal block scalars, so unsetting
sync.remote rewrote text the operator had written under a `notes: |`.
Skip a block scalar's body: it is data, not structure.

Finally, drop normalizeYamlKey and its empty keyAliases map. It has been
an identity function whose comment claimed it renamed keys.

* docs(changelog): record the dotted config key fix under Unreleased

It is the most user-visible fix on this branch and it was not in the
changelog, so it would not have reached the release notes or
`bd upgrade review`.

* fix(config): preserve existing flat dotted keys (GH#6594)

Keep literal dotted keys in their existing shape, align the direct reader with Viper precedence, and warn when both flat and nested spellings coexist.

Agent-Signature: codex-gpt-5-unknown-reasoning on behalf of Rongjun GENG

* fix(config): anchor the dotted unset walk to the key it was asked about

Review fixes for PR #6574 (maintainer iteration 1).

The new nested matcher in `commentOutYamlKey` anchored neither end of the
walk, so `bd config unset <dotted key>` commented out keys it does not own
and could leave the named target live while reporting success — the silent
divergence this PR exists to end. Two independent defects in one loop:
segment 0 matched at any indent, so a `dolt:` section under an unrelated
top-level key seeded the walk; and a key line merely deeper than the matched
parent was stepped over rather than ending the match, so an interposed
section was skipped instead of blocking descent. On

    sync:
        sub:
            remote: keep
        remote: target

unsetting `sync.remote` cut `sync.sub.remote` and left `sync.remote` live.
The walk now requires segment 0 at top level and every later segment to be a
direct child, treating any other key line as an opaque subtree to step over.
All four reviewer seeds are pinned in the unset table, which is generalized
to carry the key under test and the keys that must survive — the old table
could not express an over-match, since every case put the leaf one level
under a top-level parent.

Also, from the same review:

- Unset refuses, instead of degrading silently, on the two shapes a line
  matcher cannot edit: a key inside a flow-style mapping (it no-opped with a
  success exit, leaving the value live) and a key whose value is a block
  scalar (the key line was commented and the body stayed behind, re-parsing
  as a value of the parent). A key that is not set is still a no-op.
- Updating an existing flat dotted key rewrites that key's line instead of
  marshaling the whole document back, which dropped blank separators,
  re-indented nested blocks from two to four spaces and collapsed comment
  alignment — a whole-file diff in a git-tracked config.yaml from a one-key
  set. The line is swapped only when it is the entire entry, keeping the
  key's own text and quoting; anything else falls back to the marshal, so a
  quoted flat key still reads back.
- The two negative `init` guards assert a read-back rather than the absence
  of the pre-PR spelling, which the writer no longer emits and which a real
  regression would therefore have sailed past.

Refs: bd-zj95, GH#6594

Maintainer iteration 2 (both findings minor, non-gating; taken because each one
falsified something this commit itself asserts):

- The one-line rewrite kept every other line byte for byte but dropped the
  trailing comment on the line it touched — a regression against the PR head,
  whose node marshal carried LineComment through, in the branch whose whole
  point is leaving a shared config.yaml alone. The note is re-appended from the
  parsed comment matched back from the right of the line, so a `#` inside a
  quoted value is not mistaken for its start. yaml.v3 hangs that comment on the
  value node, not the key node as the review prescribed, except when the value
  is empty; both are consulted and both are pinned. The existing pin seeded its
  note on a bystander key and so could not see the loss; it is now on the key
  under test.
- The unset refusal walked only the nested spelling, so a literal
  `dolt.host: |` still had its key line commented out and its body orphaned at
  the top level, leaving the whole file unparseable with a success exit — while
  the changelog sentence this commit added says that case reports an error. One
  lookup of the literal key closes the gap.

The gate's doc comment no longer claims to cover the class; it is two known
shapes, and it names the members still outside it.

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: Rongjun GENG <rj.geng@gmail.com>
2026-09-23 02:28:52 -07: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 test: reconcile the sqlite-era tests the reapply left asserting live support 2026-07-18 02:43:57 +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 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
.github test(tracker): add real UOW proxy conformance fixture (#6445) 2026-09-23 02:19:18 -07:00
backend Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
beadserrors chore(api): mark new exported packages experimental before v1.3.0 (#6036) 2026-08-29 16:01:30 -07:00
cmd/bd fix(config): dotted keys round-trip through SetYamlConfigInDir/UnsetYamlConfig (bd-zj95, 1.3.1) (#6574) 2026-09-23 02:28:52 -07:00
docs Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
engdocs Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
examples security: v1.3.0 dependency + toolchain bumps (7 reachable stdlib advisories, criticals triaged) (#6047) 2026-08-28 23:26:04 -07:00
format fix(ui): stop using blocked ● for priority in CLI output (#5511) 2026-08-10 06:19:51 -07:00
integrations Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
internal fix(config): dotted keys round-trip through SetYamlConfigInDir/UnsetYamlConfig (bd-zj95, 1.3.1) (#6574) 2026-09-23 02:28:52 -07:00
issueops Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
journalops chore(api): mark new exported packages experimental before v1.3.0 (#6036) 2026-08-29 16:01:30 -07:00
memoryops chore(api): mark new exported packages experimental before v1.3.0 (#6036) 2026-08-29 16:01:30 -07: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
plugins/beads 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
release-gates fix(metrics): stop failing the reap test on a transient zombie (#6262) 2026-09-08 18:16:35 -07:00
schema chore(api): mark new exported packages experimental before v1.3.0 (#6036) 2026-08-29 16:01:30 -07:00
scripts fix(test): reap dolt sql-servers leaked by killed test runs, and fail the suite that leaks (#6441) 2026-09-22 15:08:40 -07:00
test chore(api): mark new exported packages experimental before v1.3.0 (#6036) 2026-08-29 16:01:30 -07:00
tests fix: TestMain teardown was dead code after os.Exit — 101 dolt containers leaked over 6 days (#5876) 2026-08-20 06:06:32 -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 build: make repository text EOL deterministic (#5319) 2026-08-10 20:48:09 -07:00
.gitignore refactor(cli): rename CPU profiling flag (#5126) 2026-07-28 22:17:13 -07:00
.golangci.yml Retire the last three wisp-switch call sites, and bound the wisp-inclusive union reads (ga-2ltro.12, ga-2ltro.7) (#5587) 2026-08-10 17:07:59 -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 fix(ui): stop using blocked ● for priority in CLI output (#5511) 2026-08-10 06:19:51 -07:00
AGENTS.md fix(ui): stop using blocked ● for priority in CLI output (#5511) 2026-08-10 06:19:51 -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 fix(storage): shared stores refuse version-bump migration without explicit consent (#5920, #5043) (#6048) 2026-08-29 21:47:24 -07:00
beads_cgo.go fix(storage): truthful legacy-backend tombstone rejection — detect present Dolt data, give the exact heal (D-8) (#6044) 2026-08-28 23:27:39 -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 fix(storage): truthful legacy-backend tombstone rejection — detect present Dolt data, give the exact heal (D-8) (#6044) 2026-08-28 23:27:39 -07:00
beads_test.go fix: TestMain teardown was dead code after os.Exit — 101 dolt containers leaked over 6 days (#5876) 2026-08-20 06:06:32 -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 fix(config): dotted keys round-trip through SetYamlConfigInDir/UnsetYamlConfig (bd-zj95, 1.3.1) (#6574) 2026-09-23 02:28:52 -07: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(nix): regenerate vendorHash for the merged module graph 2026-09-15 22:19:02 +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 Guard and qualify historical upgrades to v1.2 (#4907) 2026-08-06 18:45:04 -07:00
go.mod Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +00:00
go.sum Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +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 Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485) 2026-08-09 11:29:32 -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 Merge release/1.3.0 into main (post-tag forward-port) 2026-09-15 22:09:13 +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
NEWSLETTER.md Retire legacy Homebrew tap publishing (#4478) 2026-06-22 19:26:46 -07:00
open_backend_selection_test.go fix(storage): truthful legacy-backend tombstone rejection — detect present Dolt data, give the exact heal (D-8) (#6044) 2026-08-28 23:27:39 -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 release: prep v1.3.0 — version bump, changelog rollup, release process docs, formula fixes (#6038) 2026-08-30 22:19:35 -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