Beads Files

beads v1.0.4

Pre-compiled binaries for Linux, macOS (Intel & Apple Silicon), Windows (AMD64 & ARM64), Android/Termux (ARM64), and FreeBSD.

Installation

Homebrew (macOS/Linux):

:::bash
brew install beads

Quick Install (macOS/Linux/FreeBSD):

:::bash
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

Windows (PowerShell):

:::powershell
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

Manual Install: Download the appropriate binary for your platform below, extract it, and place it in your PATH.

Changelog

Features

• [ecb954] feat(close): add --reason-file flag mirroring --body-file pattern
• [336728] feat(config): add central server config library (#3258)
• [097ed1] feat(linear): add OAuth client-credentials support
• [6584ff] feat(linear): add ambient staleness signal for auto-fresh data
• [0ec4a9] feat(linear): add idempotency markers to prevent duplicate issue creation
• [989d0f] feat(linear): add per-workspace concurrency lock on sync
• [06d385] feat(linear): add type mappings for decision, spike, story, milestone (#3651)
• [ac15e0] feat(linear): adopt issueBatchCreate/issueBatchUpdate for 50x efficiency (#3654)
• [a845bc] feat(linear): parse Retry-After headers and add rate-limit circuit breaker
• [e90f98] feat(setup): omit bd dolt push from template when no remote configured
• [7358de] feat: add -C <path> flag to change directory before running (#3442)
• [0bc4c7] feat: add JSONL bulk dep add (#3530)

Bug Fixes

• [60cbf8] fix(cli): swap CommandStyle LightDark arguments for light terminals (GH#3611) (#3643)
• [1ebee7] fix(cli): swap CommandStyle colors for correct light/dark contrast (GH#3611)
• [033853] fix(close): adapt routed close to current main
• [564bd1] fix(close): route ID resolution like show/update (beads-0km)
• [0c5199] fix(comments): helpful error for misplaced bd comments list (GH#3542) (#3641)
• [74b107] fix(config): check ~/.config/bd/config.yaml on macOS
• [4fbfd9] fix(config): consult config.yaml for dolt.host (#3471)
• [10bf49] fix(config): format OAuth config changes
• [860ddb] fix(config): format wisp privacy changes
• [918eb8] fix(config): refuse to write secret keys to git-tracked config.yaml (#3652)
• [a6f2d8] fix(config): remove dead dolt.idle-timeout key (GH#2452-followup)
• [21c55f] fix(create): handle dependency aliases in --deps
• [218349] fix(dep): only show [BLOCKED] for genuine blocking deps in dep tree (GH#3565) (#3675)
• [f0b6d4] fix(dep): show dependency type in bd dep tree output (GH#3565) (#3647)
• [ccfb97] fix(dep): tolerate unresolved IDs in batch dep list (#3620)
• [be65f5] fix(dolt): batch wisp-ID partition in bulk hydrators (GH#3414)
• [4affe4] fix(dolt): distinguish fsck open-failures from integrity failures (#3465)
• [fbcdb9] fix(dolt): preserve label hydration wisp-set callers
• [607919] fix(dolt): skip git hooks on internal push of refs/dolt/data (GH#3724) (#3740)
• [759636] fix(embeddeddolt): pass DOLT_REMOTE_USER to push/pull/fetch
• [7978fa] fix(export): exclude ephemeral wisps from bd export by default (GH#3649)
• [61e85b] fix(export): exclude memories from bd export by default (GH#3650)
• [226e7f] fix(export): include NoHistory beads when Ephemeral=&false filter is active
• [651a52] fix(export): sort memory keys for deterministic JSONL output (GH#3474) (#3482)
• [c67e41] fix(federation): respect ephemeral/wisp type filters during sync
• [7fb4c3] fix(formula): carry step labels through cook and pour
• [7e8766] fix(gate): drop removed 'merged' field from gh pr view call (GH#3411) (#3488)
• [b32416] fix(github): map decision, spike, story, milestone GitHub type labels (GH#3604) (#3639)
• [dccfa2] fix(graph): emit [] not null for empty links in HTML output (GH#3592)
• [a02850] fix(graph): merge components for bd graph --all --html (GH#3592) (#3648)
• [b5d8c4] fix(history): respect --json flag when issue has no history (#3503)
• [3be9f0] fix(hooks): auto-import .beads/issues.jsonl after pull/checkout (GH#3729) (#3730)
• [ad8d6d] fix(hooks): inject BEADS INTEGRATION above trailing exec block (GH#3537) (#3556)
• [0db2a6] fix(hooks): preserve user content when migrating v0.62.x → v1.0.x (GH#3536) (#3557)
• [2efac7] fix(hooks): use BeadsDirPerm (0700) for .beads/hooks directory (#3616)
• [bcd576] fix(init): add FixBeadsDirPermissions stub for Windows build
• [a0cf5e] fix(init): chmod existing .beads/ to 0700 instead of only warning (GH#3391)
• [7d3dc1] fix(init): only strip world-accessible bits, preserve group perms
• [f34ab8] fix(init): repair existing .beads permissions to 0700
• [c9eb8e] fix(init): sanitize dotted prefixes consistently (beads-oko)
• [e643e9] fix(linear): add done/deferred/pinned/hooked aliases to ParseBeadsStatus (#3718)
• [b8e756] fix(linear): address maintainer blockers on idempotency PR
• [46584d] fix(linear): address maintainer feedback on OAuth client-credentials PR
• [3e804c] fix(linear): address maintainer feedback on PR [#3655]
• [dc4cd8] fix(linear): clean rate-limit lint
• [d33687] fix(linear): clean staleness lint
• [cb1a07] fix(linear): clean sync lock lint
• [f172b9] fix(linear): correct issueBatchCreate GraphQL variable type (#3703)
• [175bc2] fix(linear): keep lock file stable across Release cycles
• [3d9a01] fix(list): --deferred returns complete deferred set (GH#3571)
• [7e3c7f] fix(list): deduplicate issues with multiple blocks dependencies (GH#3567) (#3673)
• [d648b6] fix(list): emphasize truncation warning with WarnStyle (GH#3580) (#3739)
• [22e9ca] fix(list): format deferred filter tests
• [7d4bf5] fix(makefile): use /dev/null instead of nul to silence stderr on windows
• [229f21] fix(mol): clear root Ephemeral on bd mol squash (#3696)
• [bbd4e4] fix(mol): recognize TypeMolecule roots in findParentMolecules (#3719) (#3721)
• [ae0fc1] fix(nix): use proxy vendor for pure-go package
• [1cfb6e] fix(plugin): move claude agent out of shared codex dir to fix plugin install
• [02bdb4] fix(prime): surface memories before hook truncation (#3692)
• [7a1f7e] fix(release): harden shipped release formula adoption (#3668)
• [f3d57d] fix(release): ship beads-release formula (#3631)
• [c9ae42] fix(setup): align Claude PreCompact hook docs
• [059d72] fix(setup): drop bd sync from Mux fallback; warn on stale Claude hooks (GH#3546) (#3642)
• [261fdb] fix(setup): format conditional push template
• [3fa0e2] fix(setup): prevent doubled BEGIN/END markers from CRLF embedded template (#3553)
• [2cfbe4] fix(setup): removeHookCommand drops sibling commands on first match
• [c5961c] fix(sort): natural numeric sort for issue IDs with dotted suffixes (GH#3477) (#3486)
• [8475f8] fix(test): thread -tags gms_pure_go to subprocess build in embeddeddolt concurrency test
• [5a180e] fix(where): avoid live reopen for server-mode selection (beads-gekl.3)
• [4fbb33] fix(where): keep bd where on the no-db path (beads-bgu)
• [555173] fix(where): restore prefix without the old slowdown (beads-ayf)
• [cb3ef7] fix: ApplyCLIAutoStart respects ServerModeExternal (#3473)
• [57ddb0] fix: bd admin commands fail with 'embedded mode' error in server mode (#3438)
• [eef21d] fix: remove duplicate wisp query in bd export (#3352) (#3372)
• [5a2fc6] fix: repair shared-server bootstrap and doctor metadata drift (#3242)
• [4a2593] fix: replace deprecated --force flag with --reinit-local in init error messages (#3695)

Others

• [adb0cc] /cmd/bd/db_proxy_child.go: cleanup
• [5e66b2] /cmd/bd/db_proxy_child.go: rebase main
• [e5bebb] /cmd/bd/dolt.go: revert message flag requirement
• [1ad700] /cmd/bd/main.go: default auto-commit on
• [a58228] /cmd/bd/main.go: remove promote gate
• [2f1cd4] /cmd/{cmd, internal}: make exports atomic writes
• [f4c46d] /go.{mod,sum}: bump dolt driver (#3435)
• [916c16] /internal/atomicfile/atomicfile.go: use io.Copy
• [252978] /internal/beads: maybe fix worktree server bug
• [6e0b6b] /internal/storage/db/doltserver.go: wip
• [a9cbf9] /internal/storage/db/proxy/server.go: more cleanup
• [e77492] /internal/storage/db/proxy/server.go: pr feedback fix
• [42b38d] /internal/storage/db/proxy/server_test.go: fix test bug
• [d7d1b3] /internal/storage/db/server/doltserver.go: ready for tests
• [04de2f] /internal/storage/db/server/doltserver.go: some fixes
• [312b5b] /internal/storage/db/server/doltserver.go: wip, dial
• [54b25a] /internal/storage/db/server/doltserver.go: wip, implement start
• [5a205f] /internal/storage/db/server/doltserver.go: wip, ping
• [aa76c4] /internal/storage/db/server/doltserver.go: wip, running
• [18ff81] /internal/storage/db/server/doltserver.go: wip, stop
• [e83e98] /internal/storage/db/server/doltserver_test.go: add socket test
• [9e49d1] /internal/storage/db/server/doltserver_test.go: keep config in tests
• [106e10] /internal/storage/db/server/testserver_test.go: add test server test
• [83813b] /internal/storage/db/server: add wait to server start
• [d3e837] /internal/storage/db/server: concurrency test
• [a4dc3f] /internal/storage/db/server: remote status check
• [65a8f4] /internal/storage/db/server: remove restart
• [efb415] /internal/storage/db/server: use abs root dir
• [5a39aa] /internal/storage/db/server: wip, need to test tests
• [cd4a22] /internal/storage/db: change to endpoint
• [8f16ba] /internal/storage/db: fix tests
• [227c74] /internal/storage/db: some additional fixes
• [40bb25] /internal/storage/db: update to kill and remove dolt sql-server
• [3667dd] /internal/storage/db: wip implement dsn
• [e3dd66] /internal/storage/db: wip, making DoltServer
• [6e0f3c] /internal/storage/db: write pid of dolt sql-server
• [dd2cd0] /internal/storage/doltserver/store.go: dolt server store
• [4151d8] /internal/storage/doltserver/store.go: get test passing
• [79c689] /internal/storage/doltserver/store.go: wip
• [273ff6] /internal/storage/doltserver/store.go: wip, need proxy
• [c7f145] /internal/storage/doltserver/store.go: wip, need schema stuff
• [ac0f6e] /internal/storage/doltserver/store.go: wip, new store
• [57d3c8] /internal/storage/doltserver: get test how i want it
• [ed3a43] /internal/storage/doltserver: get test how i want it
• [396911] /internal/storage/{db,doltserver}: add shutdown helper for tests
• [e8c5d6] /internal/storage/{db,doltutil}: linting
• [e8d4d6] /internal/storage: remove Ping from DatabaseServer
• [dcc683] /internal/storage: some lint
• [a05e06] /internal/storage: wip, need to create db if not exists
• [6a2f85] /{.github,internal}: remove comments, install dolt in ci
• [58dc2e] /{beads_cgo,cmd,internal}: cache open embedded stores deterministically to prevent deadlocking when multiple store open attempts are made against an opened store
• [d0fd47] /{cmd,internal}: add test server
• [e21118] /{cmd,internal}: fix import jsonl
• [dad89e] /{cmd,internal}: fix linting
• [73f2ab] /{cmd,internal}: maybe fix tool tip closed store bug
• [05251d] /{cmd,internal}: some cleanup
• [b0a333] /{cmd,internal}: some cleanup
• [b83fdb] /{cmd,internal}: some fixes
• [bed5e5] /{cmd,internal}: wire up db proxy child
• [7e0d09] /{internal,cmd}: fix CommitPending
• [e97532] :remove uneccessary locking
• [dcb105] Add Linear state_map dotted config regressions (#3500)
• [f7269b] Add Linear state_map dotted key regressions (bd-cba)
• [a97eec] Add atomic ready claim (GH-3570)
• [112be8] Add bd init --remote bootstrap path (#3527)
• [4f1c29] Add explicit Codex skill setup (#3670)
• [0fffa4] Add external server CLI dir override (bd-fn9) (#3498)
• [46be55] Add maintainer PR guidelines (bd-k0j) (#3665)
• [43715a] Add shared Beads plugin package
• [3e56f0] Document Linear external_ref pre-linking (#3517)
• [e2e497] Document supported go install modes (bd-o5a) (#3480)
• [d33799] Drop redundant trailing comments on Labels and Metadata copies
• [e9ebb2] Fix Nix CI Go toolchain selection (bd-7mh.6)
• [b5448e] Fix Nix lock hash (bd-7mh.6)
• [52fc26] Fix gate and cook regressions (bd-r2l)
• [bb6b8f] Fix ready/list UX regressions (#3481)
• [2f60a1] Import Linear relations as dependencies (#3519)
• [f481b7] Keep Nix CI smoke test local (bd-7mh.6)
• [16c0cd] Merge PR [#3483]: fix init permissions repair
• [425ae2] Merge main into OAuth client credentials branch
• [f11830] Merge main into OAuth client credentials branch
• [f4a1a2] Merge main into staleness signal branch
• [ef3c99] Merge remote-tracking branch 'origin/main' into bd-where-is-slow
• [f993aa] Merge remote-tracking branch 'origin/main' into bd-where-is-slow
• [ea9fa3] Merge remote-tracking branch 'origin/main' into fix/export-exclude-memories
• [69cd8a] Merge remote-tracking branch 'upstream/main' into bd-where-is-slow
• [cc31c6] Rebalance embedded cmd CI shards (bd-8zg) (#3499)
• [b0ab39] Refresh Nix lock target (bd-7mh.6)
• [e93d42] Repair ignored wisp dependency table bootstrap (bd-8e8) (#3497)
• [42064c] Sync Linear milestones as local epics (#3528)
• [85cbde] Update Nix vendor hash for Go 1.26 (bd-7mh.6)
• [a2db80] auto-import: don't print progress message before confirming import needed
• [275bdb] auto-import: remove redundant commandDidWrite in fallback path
• [6c9384] changelog: document OpenBestAvailable breaking change and flock removal
• [24486d] chore(deps): bump DeterminateSystems/determinate-nix-action (#3635)
• [332357] chore(deps): bump actions/setup-go from 5.6.0 to 6.4.0 (#3636)
• [2841d9] chore(deps): bump pydantic in /integrations/beads-mcp (#3467)
• [7d94c2] chore(deps): bump pydantic-settings in /integrations/beads-mcp
• [87e698] ci(docs): add --fallback-extensions html to lychee link check (#3736)
• [73507c] ci(regression): pull Dolt sql-server image so tests use shared container (#3737)
• [2cd886] ci: mint Homebrew tap token from GitHub App (#3472)
• [e19e31] docs(agents): add Storage Boundary section to AGENTS.md (#3617)
• [51f8fa] docs(changelog): note bd close routing fix (beads-5wr, GH#3608)
• [8b7cbf] docs(claude): make root agent guide a source pointer (#3795)
• [2e1a0d] docs(codex): add skill path hint and marker-coexistence note (#3735)
• [f7b797] docs(doctor): align interactions.jsonl policy with bd audit (GH#3622) (#3645)
• [45c7a6] docs(templates): prepend architecture summary to bd-init AGENTS.md (GH#3683) (#3727)
• [56cc30] docs(website): config.toml → config.yaml in git-integration.md (GH#3683-followup)
• [8694c5] doctor: detect AGENTS.md / CLAUDE.md user-authored divergence (#3600)
• [4fcad2] fix(auto-export): surface git add stderr in failure warning
• [cc34fb] fix(storage/dolt): apply ExcludeLabels in GetReadyWork (#3479)
• [b78a62] github: classify rate-limit 403s and stop the push loop when one hits (#3624)
• [b9e16a] init: harden --remote error path and broaden test coverage (#3558)
• [c61f97] refactor(where-tests): share JSON assertions for selected-db cases (beads-yi0o)
• [674561] schema: make DROP COLUMN migrations idempotent (fixes migration 0032 loop) (#3418)
• [ba9d25] test(close): table-driven routing-fallback tests (beads-bn1)
• [539fb6] test(cmd/bd): build-tag cgo-only test helpers so pure-go tests compile (#3716)
• [c27aa2] test(config): add XDG config path tests for macOS
• [609dce] test(export): add export globals to saveAndRestoreGlobals for isolation
• [195ee6] test(init): cover config-sourced dotted prefix normalization (beads-gekl.2)
• [759456] test(permissions): add regression coverage for FixBeadsDirPermissions
• [911137] test(where): cover BEADS_DB precedence over BD_DB (beads-gekl.1)
• [d71a3a] test(where): cover no-db command selection
• [f95430] test(where): cover prefix fallback decisions (beads-53zb)
• [2514d2] test(where): cover remaining prefix resolution branches (beads-454u)
• [ac98e6] {cmd,internal}: wip, proxy database server