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
Wilhelm Uschtrin 721e42e680
fix(notion): make the query page bound configurable and honour Retry-After (#6006)
* fix(notion): make the query page bound configurable and honour Retry-After

QueryDataSource paginates up to maxQueryPages (50) x maxPageSize (100), so a
data source larger than 5000 rows cannot be synced at all: the call returns an
error rather than partial results, and because every CLI narrowing flag is
applied after it returns, no flag works around it. Sync dies in both directions
at once. Refs #6004.

Two changes, and the second is what makes the first safe:

- Client.MaxQueryPages / WithMaxQueryPages lets a caller raise the bound for a
  large data source. Default behaviour is unchanged when unset. The error at the
  bound now names the ceiling in rows as well as pages, since rows is the number
  a caller can compare against their own data source.

- doRequest now retries 429 and 529 honouring Retry-After, with exponential
  fallback clamped at 30s. Notion enforces ~3 requests/second per connection, so
  raising the page bound without this would trade a clear failure for an
  intermittent one. Other 5xx retry only for GET/DELETE — replaying a POST that
  may already have been applied server-side is how duplicates get made.

The request body is now marshalled once and the reader rebuilt per attempt; a
retry cannot reuse a drained body.

Tests cover the configured bound, the unchanged default, Retry-After being
obeyed exactly, GET retrying on 5xx, and POST not retrying. Verified they bite:
forcing maxRequestAttempts to 1 fails exactly the two retry tests, and ignoring
the configured bound fails exactly the bound test.

make build and make fmt-check pass; internal/notion and internal/tracker pass
with -tags gms_pure_go. golangci-lint was not run locally (not installed on this
machine); CI will cover it.

* fix(notion): use US spelling so misspell passes

The repo pins misspell to locale: US, and CI flagged "honouring" in
internal/notion/client.go. Corrected there, and in the two occurrences in
client_test.go - those are not linted today (run: tests: false) but leaving
British spellings in place only plants a failure for whenever that changes.

Verified with misspell v0.8.0 -locale US: the pre-fix content reports both
occurrences, the fixed content reports none. internal/notion tests pass with
-tags gms_pure_go, including the renamed test.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N4YFBBWN33GZZ2BDxWRvjT

* fix(notion): address review — 529 verb gate, ctx-aware retry wait, CLI wiring

MAJOR 1. retryableStatus returned early on 429 *or* 529 before the verb gate, so
529 was retryable for every verb — including CreatePage and CreateDatabase. A
529 can come back after Notion's edge already handed the write to the origin, so
a replay creates a second row for one bd issue, and ensureRemoteIndex is
last-write-wins on the bd ID, so nothing surfaces it. 429 stays verb-agnostic
(Notion rejects rate-limited requests before processing them); 529 now sits
under the GET/DELETE gate with the other 5xx. Three tests pin the boundary: a
creating POST makes one attempt on 529, a GET retries on 529, and a creating
POST still retries on 429.

MAJOR 2. The retry wait polled ctx.Done() with a default: and then slept, so
cancellation was ignored for up to maxRetryDelay per attempt — and
QueryDataSource pays that per page, scaling with the very bound this change
lets callers raise. Replaced with wait(ctx, d): a blocking select over
ctx.Done() and a channel from a c.after hook, time.After by default.

MAJOR 3. The bound is now reachable from the CLI. Tracker.Init reads
notion.max_query_pages / NOTION_MAX_QUERY_PAGES and threads it into the client;
unset keeps the client's own default, and a value that is set but unusable is an
error rather than a silent fallback — the operator sets that key precisely
because sync is already failing on the bound. The pagination error names those
levers instead of a Go method a CLI user cannot call.

Also: assert every attempt carries a non-empty body (a drained reader would send
an empty second one, and nothing noticed); drop the unreachable lastErr branch
by breaking out of the loop; pin retry exhaustion at exactly maxRequestAttempts
with the last attempt's error; table-test parseRetryAfter across the nine
interesting inputs; name the 529 literal; hardcode 50 in the default-bound test
so lowering the default fails it; atomic counters in tests.

Every new test verified to bite by reverting each fix in turn: each mutation
fails exactly the tests naming it, against a clean baseline.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(notion): refuse a Retry-After longer than the client will wait

Separate commit because this one is a judgement call, not a defect fix — drop it
on its own if you would rather keep clamp-and-retry.

With Retry-After: 3600 the old path clamped to 30s and retried four times, so a
server asking for an hour got four more requests inside two minutes — the window
it told us to stay out of, and the way that window gets extended. Now the call
returns immediately, naming the delay the server asked for, and the caller
decides.

A Retry-After equal to maxRetryDelay is still honoured and waited out; only a
longer one is refused. The underlying API error is wrapped, so nothing is lost
to a caller inspecting it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(notion): key retry on side-effect safety, jitter own backoff, honour both Retry-After forms

Maintainer review fixes for PR #6006 (review iterations 1 and 2). All changes are
inside internal/notion; no new files.

F1 (major) — the 5xx/529 retry arm could never fire on POST
/data_sources/{id}/query, the paginating endpoint this PR exists to protect,
while the MethodDelete half of the allowlist had no call site at all (a census of
the client's verbs returns 3 GET / 3 POST / 2 PATCH, zero DELETE). Replaced the
verb gate with a retrySafety value each call site declares, so the property being
tested is side-effect safety rather than a proxy for it, and dropped the dead
MethodDelete arm. Only the read-only query POST changes behaviour: the creating
POSTs and both PATCHes stay non-replayable on every status except 429, exactly as
before. TestClientDoesNotRetryServerErrorOnPost exercised the query endpoint
while its "may already have been applied server-side" rationale could not be true
there, so it is retargeted at CreatePage and renamed
...OnCreatingPost, pairing with the existing 529 twin;
TestClientRetriesServerErrorOnQueryPost pins the new behaviour.

F2 (minor) — the exponential fallback had no jitter, unlike both sibling tracker
clients, so N processes tripping the same ~3 req/s limit retried in lockstep.
Jitter is applied to the self-chosen ladder only, never to a server-mandated
Retry-After, mirroring the split in internal/jira/client.go:419-424.

F3 (minor) — parseRetryAfter collapsed absent, HTTP-date and a legal
"Retry-After: 0" into one sentinel, so a date-form wait routed around the
maxRetryDelay refusal its delta-seconds twin is subject to. It now parses both
RFC 9110 forms and returns a presence flag; the doc comment's old justification
went with the behaviour it described.

F4 (nit) — maxRequestAttempts' comment claimed coverage of "transiently failing"
requests, which the transport arm does not have.

F5 (nit) — the invalid-value error names NOTION_MAX_QUERY_PAGES as well as the
config key, an abandoned wait now carries the API failure that caused it
alongside ctx's error, and the long-Retry-After refusal is evaluated before the
exhaustion break so the operator still gets it on the final attempt. That last
pin is a sibling test rather than a case inside
TestClientExhaustsRetriesAndReturnsTheLastError as the review suggested, to keep
that test a single-purpose pin on the loop's exit arithmetic.

Iteration 2 (non-gating, both in parseRetryAfter, which F3 already reworks) —
a delta-seconds value too large for a Duration now saturates instead of letting
the multiply wrap: "9223372037" wrapped to -2562047h47m16.7s, which is under
maxRetryDelay, so the refusal let it through to immediate retries. The date
form already saturated via time.Until. The unchecked multiply predates this
fixup (it is at the contributor's head) and is shared by linear/jira/gitlab,
which are left to a follow-up. TestClientRefusesLongRetryAfterInHTTPDateForm
drives a date-form header through the client, so the date form reaching the
refusal is pinned by the loop rather than only by TestParseRetryAfterHTTPDate's
arithmetic.

Validation: internal/notion 85 PASS / 0 FAIL / 0 SKIP; go build ./... and go vet
./cmd/bd (the sole importer) clean; CGO_ENABLED=0 builds; gofmt clean;
golangci-lint 0 issues both unscoped and --new-from-rev at the upstream base, and
the added //nolint:gosec is load-bearing (removing it reproduces exactly the G404
it names). Each fix is mutation-proved: reverting it reds its own pin while the
neighbouring pins stay green, including the two creating-POST controls under F1,
both directions of F2's jitter split, and both sides of the saturation bound.
Keying the refusal to delta-seconds only reds the new date-form test alone,
while TestParseRetryAfterHTTPDate stays green.

Moving the new delay logic into retryDelay rather than nesting it in the loop
took doRequest — the run's worst_changed function — from cyclomatic 21 /
cognitive 32 to 19 / 28 (gocyclo, gocognit), out of the major cyclomatic band
instead of further into it. No BUILD.bazel change is owed: no file was added and
both added imports (math, math/rand/v2) are stdlib.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
2026-10-04 07:16:26 -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 fix(release): name the version-drift remedies that work (#7083) 2026-10-01 11:34:06 -07:00
.github test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
backend fix(ci,tests): un-hide TestEmbedded* tests, fence cmd/bd tests from ancestor .beads, cut #7051 race long poles, fix main lint (#7128) 2026-10-03 04:18:14 -07:00
beadserrors test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
cmd/bd fix(routing): bind role detection to the bd -C target repo (re-port of #4242) (#5243) 2026-10-04 05:47:27 -07:00
docs fix(backup): point the size-cap pause advice at levers that end it (#7074) 2026-10-01 08:05:46 -07:00
engdocs test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07: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 build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
integrations ci: package gates start after rbe, MCP pytest -n 8, gate jobs on Blacksmith (F3) (#7126) 2026-10-03 00:03:43 -07:00
internal fix(notion): make the query page bound configurable and honour Retry-After (#6006) 2026-10-04 07:16:26 -07:00
issueops feat(httpapi): opt-in large issues:batchApply envelope (≤1000 items, one transaction) (#7051) 2026-10-01 08:32:56 -07:00
journalops test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
memoryops test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -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 fix: make release-version checks shell-free (#5614) 2026-10-01 07:46:37 -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 build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
scripts test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
test test(bazel): hermetic test env + inject bd binary into subprocess tests (#6843) 2026-09-27 11:38:03 -07:00
tests ci(bazel): embedded-Dolt tier 20/5 → 50/15 duration-balanced Bazel shards (F1) (#7156) 2026-10-03 21:30:03 -07:00
third_party/patches ci(bazel): PR-gate parity lanes (docker, pure-Go, js/wasm) + bd artifact (#6887) 2026-09-28 02:03:51 -07:00
tools test(cmd/bd): drop dead unsupported-storage test, CWD-independent bd fallback build, stop BEADS_DIR leaking between in-process runs (#7171) 2026-10-03 23:44:37 -07:00
winget fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134) 2026-09-30 20:24:59 -07:00
.bazelignore test(bazel): runfiles helpers + declared inputs for scan-guard tests (#6828) 2026-09-27 08:24:08 -07:00
.bazelrc test,ci(cmd/bd): run the Dolt-gated cmd/bd suite (advisory Bazel lane), fix in-process runner leaks and rotted tests; init --quiet stays quiet (#7185) 2026-10-04 03:06:54 -07:00
.bazelversion build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -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 build(bazel): side-by-side Bazel scaffold + policy tests (#6798) 2026-09-27 03:41:02 -07:00
.golangci.yml fix(output): route graph renderers and ratchet stdout writes (#5624) 2026-09-30 15:55:33 -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(update): fence unforced --notes overwrites behind --force across all surfaces (#5946) 2026-10-01 05:02:40 -07:00
AGENTS.md fix(update): fence unforced --notes overwrites behind --force across all surfaces (#5946) 2026-10-01 05:02:40 -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 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 ci: parallel PR Lint matrix with pinned golangci-lint, fold duplicate Lint, split scripts-go-checks (F5) (#7127) 2026-10-03 09:36:20 -07:00
CHANGELOG.md fix(proxy): fail fast with a clear MySQL error when an external upstream is unreachable (#7181) 2026-10-04 02:37:58 -07:00
checks.nix Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -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 ci: advisory workflows on Blacksmith with restore-only caches, folded matrices, path filters (F7c) (#7147) 2026-10-03 16:03:39 -07:00
CONTRIBUTING_PR_GUIDELINES.md docs: add CONTRIBUTING_PR_GUIDELINES.md (codify reviewer expectations for contributors) (#3913) 2026-07-06 22:12:29 -07:00
default.nix chore(deps): bump the go-deps group across 1 directory with 20 updates (#6494) 2026-09-27 01:07:14 -07:00
errors_test.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
export_dependency_add_options_test.go feat: export DependencyAddOptions from the root package (#4870) 2026-07-17 20:34:32 -07:00
FEDERATION-SETUP.md chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
flake.lock flake.lock: Update (#4501) 2026-07-08 12:21:24 -07:00
flake.nix Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
go.mod fix(sql): classify bd sql statements with the SQL parser; never drop result sets (#6932) 2026-09-29 01:08:10 -07:00
go.sum chore(deps): bump the go-deps group across 1 directory with 20 updates (#6494) 2026-09-27 01:07:14 -07:00
install.ps1 docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
issue_lifecycle_external_test.go feat(storage): one guarded issue-lifecycle surface for the CLI and linked consumers (#5191) 2026-07-31 11:26:38 -07:00
issue_roles_external_test.go 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 fix(ci): resolve gofmt from go.mod's toolchain, not PATH (be-gx8) (#6294) 2026-09-30 18:38:46 -07:00
mint.sh chore: purge deleted docs-pipeline references from release tooling, CI, and repo plumbing 2026-07-12 11:07:26 -07:00
MODULE.bazel fix(sql): classify bd sql statements with the SQL parser; never drop result sets (#6932) 2026-09-29 01:08:10 -07:00
MODULE.bazel.lock test(bazel): hermetic test env + inject bd binary into subprocess tests (#6843) 2026-09-27 11:38:03 -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 fix(prime): describe the memory split instead of prohibiting MEMORY.md (#6111) 2026-09-29 01:23:19 -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
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 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 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 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