🚨 This release is gated — do not upgrade

v1.0.5 contains a migration (0043) that can silently and unrecoverably break multi-machine bd dolt sync after both clones upgrade. See #4259.

• Homebrew has been reverted to v1.0.4 (unaffected); a fixed v1.0.6 is in progress.
• Already on 1.0.5? Do not run bd dolt push/pull across machines until 1.0.6.

This release is kept as a pre-release for the in-flight fix only.

beads v1.0.5

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (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

• 12bb76b feat(config): add dolt.mode config key with ambiguous-config warning
• d476fba feat(config): validate dolt.mode accepts server or embedded
• 82020c4 feat(init): auto-configure contributor routing on fork detect (be-7daa14) (#4028)
• e49bc91 feat(list): be-a5z add --skip-labels hydration toggle (AD-02)
• 7da4f78 feat(schema): schema-skew guard — hard fail on forward DB drift (be-wwbsv)
• 287d8a8 feat(setup): Gemini/Claude hook JSON compliance, --hook-json flag, legacy migration
• cfcc957 feat(show): count-only JSON details with opt-in streamed payloads
• 05c7835 feat(storage): honor .beads/config.yaml types.custom in server-side validation (#4024) (#4026)
• 25703f8 feat: add Copilot CLI setup recipe (#3839)

Bug Fixes

• 78cacb9 Revert "fix(ci): create flake lock PRs from fork"
• 3c8c8be fix(audit): widen newID entropy to 16 bytes + bump test to 8000 IDs (be-5uxe)
• 3b841e1 fix(audit): widen newID entropy to 8 bytes (be-yc9h)
• 26a7a96 fix(ci): create flake lock PRs from fork
• 598a4d2 fix(ci): use app token for flake lock PRs
• a180c63 fix(close): support per-id reasons (#4194)
• 1f2ec3c fix(close): treat re-close of already-closed issue as idempotent success (GH#4025)
• 0afd3d5 fix(codex): ship hook release safely
• f8b9400 fix(create): commit labels during initial issue creation (#4149)
• cbef9fb fix(create): set status=deferred when --defer date is in the future (GH#4071)
• 480ffe4 fix(create): warn on unknown fields and honor --dry-run with --graph (#3762)
• 660250e fix(dep): keep relates-to out of dependency tree
• 4ad5b53 fix(doctor): stop emitting fresh-clone false positive in Dolt server mode (#3755)
• d7d3dad fix(dolt): adopt git origin on first push (#3940)
• 2a5a980 fix(dolt): bd dolt status probes SQL when local server is externally-managed
• 32586cb fix(dolt): detect managed handoff port conflicts (#4217)
• 52cc8be fix(export): fail on auto-export git add errors
• 663bc01 fix(export): guard auto-export against richer JSONL overwrite
• 9e956db fix(export): guard empty auto-export over populated JSONL
• 36f7e8a fix(hooks): address review timeout edge cases
• 85549f4 fix(hooks): bound prime and hook waits
• 5629e18 fix(import): preserve JSONL comment IDs (#4103)
• be0aa70 fix(init): apply config server mode before validation
• f6f1c00 fix(init): hard-fail when dolt.host/dolt.port set without server mode
• 278b24a fix(init): honor dolt local-only remote wiring (#4227)
• 3988db7 fix(init): make JSONL auto-export opt-in (#4063)
• f4c3adf fix(init): mark server-mode Dolt dirs compatible
• 1837fff fix(init): narrow hard-fail to remote host, not port-only
• 6467c4f fix(init): platform-accurate config path in warning and add init test coverage
• 8ba0b46 fix(init): surface marker write failures
• 220e552 fix(init): tighten Dolt marker handling (#4083)
• 0c47b3c fix(init): use git origin as default Dolt remote (#3909)
• 602593b fix(install): use declared module path for go fallback (#4215)
• c17f3fd fix(list): honor skip-labels in JSON output
• 7f8baea fix(list): keep relates-to out of bd list tree mode (#3936)
• 8a8a2ec fix(mcp): route validate and detect-pollution to bd doctor (GH#4037)
• 4cba4ef fix(migration): run schema migrations on a connection with no read timeout
• e4a0b2c fix(mol): bd mol wisp materializes full child DAG by default (#3872) (#3911)
• ed2b5ae fix(ready): apply filters to wisp ready work (#4008)
• 6a5c9e3 fix(schema): migrate TEXT → LONGTEXT for large-content columns (be-knye)
• bbd91cb fix(schema): panic on duplicate migration version numbers
• 6a5fb83 fix(schema): preserve wisps DEFAULT '' and renumber LONGTEXT migration → 0046 (be-knye)
• 028690b fix(schema): qualify go install guidance with gms_pure_go
• 34936e2 fix(schema): renumber duplicate release migrations
• 1f073c5 fix(schema): reorder 0041 FK before generated column for Dolt 2.0.6 (#4120)
• 376a24a fix(schema): serialize Dolt schema migrations (#4005)
• 35b9bbb fix(schema): unify migration advisory lock path (#4031)
• 4a24bc3 fix(schema): update renumbered migration comment (#4235)
• 6143a19 fix(schema): widen events/wisp_events value columns to LONGTEXT (be-kkp)
• 4db8d74 fix(setup): clarify symlinked agents skip
• f52c78b fix(setup): finish hook JSON migration
• 86545f6 fix(setup): harden symlink follow-up handling
• 09a3890 fix(storage): preserve mixed issue and wisp reads (#3991)
• 99653e0 fix(trackers): route secret keys through config.yaml in all tracker getConfig methods
• 88aa88d fix(update): clear external_ref to SQL NULL when --external-ref "" (#3912)
• c0bdf49 fix: guard JSONL auto import/export edge cases
• e569c74 fix: materialize local table schemas for branch tests (#4014)
• 7f7708e fix: preserve Windows drive remotes for dolt sync
• 8ae4c3c fix: repair PR4107 blocked-state corruption (#4139)
• 3068bc4 fix: skip auto-backup file:// register on external Dolt server (#3523)

Others

• 24a1a93 /.github/workflows/ci.yml: run tests in CI
• 2985630 /cmd/bd/init.go: disable again
• bd02b5e /cmd/bd/init.go: experimental
• bcad825 /cmd/bd/init.go: remove comment
• a65d9d1 /cmd/bd/init.go: some more fixes
• 23e11ff /cmd/bd/store_factory_nocgo.go: fix build
• 9c88107 /cmd/bd: cleaning up
• cb04e03 /cmd/bd: get compiling again
• 55b302a /cmd/bd: some cleanup
• 9a5cd78 /cmd/bd: wip need tests
• 04a922c /internal/storage/db/proxy/server.go: lint
• bd1a0dd /internal/storage/dbproxy/server: fix test
• 7ce1330 /internal/storage/dbproxy/server: wip, external dolt server
• 41a5107 /internal/storage/dolt: fix after rebase
• 64ed6c0 /internal/storage/doltserver/store.go: fix panic
• 1075ec3 /internal/storage/doltserver/store.go: fixes
• e346490 /internal/storage/domain/db: comments
• d56ca38 /internal/storage/domain/db: dependency
• a873d5e /internal/storage/domain/db: handle wisps too
• 5a1d5b4 /internal/storage/domain/db: issue
• 93b63c7 /internal/storage/domain: add event
• 80194d1 /inter...

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):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (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

• ecb9542 feat(close): add --reason-file flag mirroring --body-file pattern
• 3367288 feat(config): add central server config library (#3258)
• 097ed1c feat(linear): add OAuth client-credentials support
• 6584ff8 feat(linear): add ambient staleness signal for auto-fresh data
• 0ec4a99 feat(linear): add idempotency markers to prevent duplicate issue creation
• 989d0f9 feat(linear): add per-workspace concurrency lock on sync
• 06d385e feat(linear): add type mappings for decision, spike, story, milestone (#3651)
• ac15e09 feat(linear): adopt issueBatchCreate/issueBatchUpdate for 50x efficiency (#3654)
• a845bc4 feat(linear): parse Retry-After headers and add rate-limit circuit breaker
• e90f980 feat(setup): omit bd dolt push from template when no remote configured
• 7358de6 feat: add -C flag to change directory before running (#3442)
• 0bc4c72 feat: add JSONL bulk dep add (#3530)

Bug Fixes

• 60cbf83 fix(cli): swap CommandStyle LightDark arguments for light terminals (GH#3611) (#3643)
• 1ebee7f fix(cli): swap CommandStyle colors for correct light/dark contrast (GH#3611)
• 0338534 fix(close): adapt routed close to current main
• 564bd1e fix(close): route ID resolution like show/update (beads-0km)
• 0c51997 fix(comments): helpful error for misplaced bd comments list (GH#3542) (#3641)
• 74b107a fix(config): check ~/.config/bd/config.yaml on macOS
• 4fbfd97 fix(config): consult config.yaml for dolt.host (#3471)
• 10bf490 fix(config): format OAuth config changes
• 860ddb2 fix(config): format wisp privacy changes
• 918eb8e fix(config): refuse to write secret keys to git-tracked config.yaml (#3652)
• a6f2d8d fix(config): remove dead dolt.idle-timeout key (GH#2452-followup)
• 21c55f4 fix(create): handle dependency aliases in --deps
• 2183499 fix(dep): only show [BLOCKED] for genuine blocking deps in dep tree (GH#3565) (#3675)
• f0b6d49 fix(dep): show dependency type in bd dep tree output (GH#3565) (#3647)
• ccfb97f fix(dep): tolerate unresolved IDs in batch dep list (#3620)
• be65f59 fix(dolt): batch wisp-ID partition in bulk hydrators (GH#3414)
• 4affe45 fix(dolt): distinguish fsck open-failures from integrity failures (#3465)
• fbcdb90 fix(dolt): preserve label hydration wisp-set callers
• 607919f fix(dolt): skip git hooks on internal push of refs/dolt/data (GH#3724) (#3740)
• 7596369 fix(embeddeddolt): pass DOLT_REMOTE_USER to push/pull/fetch
• 7978fae fix(export): exclude ephemeral wisps from bd export by default (GH#3649)
• 61e85bc fix(export): exclude memories from bd export by default (GH#3650)
• 226e7f2 fix(export): include NoHistory beads when Ephemeral=&false filter is active
• 651a52a fix(export): sort memory keys for deterministic JSONL output (GH#3474) (#3482)
• c67e41e fix(federation): respect ephemeral/wisp type filters during sync
• 7fb4c31 fix(formula): carry step labels through cook and pour
• 7e8766d fix(gate): drop removed 'merged' field from gh pr view call (GH#3411) (#3488)
• b324166 fix(github): map decision, spike, story, milestone GitHub type labels (GH#3604) (#3639)
• dccfa20 fix(graph): emit [] not null for empty links in HTML output (GH#3592)
• a028506 fix(graph): merge components for bd graph --all --html (GH#3592) (#3648)
• b5d8c46 fix(history): respect --json flag when issue has no history (#3503)
• 3be9f00 fix(hooks): auto-import .beads/issues.jsonl after pull/checkout (GH#3729) (#3730)
• ad8d6de fix(hooks): inject BEADS INTEGRATION above trailing exec block (GH#3537) (#3556)
• 0db2a66 fix(hooks): preserve user content when migrating v0.62.x → v1.0.x (GH#3536) (#3557)
• 2efac71 fix(hooks): use BeadsDirPerm (0700) for .beads/hooks directory (#3616)
• bcd5763 fix(init): add FixBeadsDirPermissions stub for Windows build
• a0cf5e6 fix(init): chmod existing .beads/ to 0700 instead of only warning (GH#3391)
• 7d3dc1a fix(init): only strip world-accessible bits, preserve group perms
• f34ab80 fix(init): repair existing .beads permissions to 0700
• c9eb8ec fix(init): sanitize dotted prefixes consistently (beads-oko)
• e643e94 fix(linear): add done/deferred/pinned/hooked aliases to ParseBeadsStatus (#3718)
• b8e7562 fix(linear): address maintainer blockers on idempotency PR
• 46584d8 fix(linear): address maintainer feedback on OAuth client-credentials PR
• 3e804cd fix(linear): address maintainer feedback on PR #3655
• dc4cd8b fix(linear): clean rate-limit lint
• d336874 fix(linear): clean staleness lint
• cb1a070 fix(linear): clean sync lock lint
• f172b97 fix(linear): correct issueBatchCreate GraphQL variable type (#3703)
• 175bc23 fix(linear): keep lock file stable across Release cycles
• 3d9a012 fix(list): --deferred returns complete deferred set (GH#3571)
• 7e3c7fb fix(list): deduplicate issues with multiple blocks dependencies (GH#3567) (#3673)
• d648b6a fix(list): emphasize truncation warning with WarnStyle (GH#3580) (#3739)
• 22e9ca3 fix(list): format deferred filter tests
• 7d4bf5a fix(makefile): use /dev/null instead of nul to silence stderr on windows
• 229f214 fix(mol): clear root Ephemeral on bd mol squash (#3696)
• bbd4e4d fix(mol): recognize TypeMolecule roots in findParentMolecules (#3719) (#3721)
• ae0fc1d fix(nix): use proxy vendor for pure-go package
• 1cfb6e5 fix(plugin): move claude agent out of shared codex dir to fix plugin install
• 02bdb4c fix(prime): surface memories before hook truncation (#3692)
• 7a1f7e4 fix(release): harden shipped release formula adoption (#3668)
• f3d57da fix(release): ship beads-release formula (#3631)
• c9ae42b fix(setup): align Claude PreCompact hook docs
• 059d729 fix(setup): drop bd sync from Mux fallback; warn on stale Claude hooks (GH#3546) (#3642)
• 261fdbb fix(setup): format conditional push template
• 3fa0e23 fix(setup): prevent doubled BEGIN/END markers from CRLF embedded template (#3553)
• 2cfbe4e fix(setup): removeHookCommand drops sibling commands on first match
• c5961c4 fix(sort): natural numeric sort for issue IDs with dotted suffixes (GH#3477) (#3486)
• 8475f8b fix(test): thread -tags gms_pure_go to subprocess build in embeddeddolt concurrency test
• 5a180ed fix(where): avoid live reopen for server-mode selection (beads-gekl.3)
• 4fbb332 fix(where): keep bd where on the no-db path (beads-bgu)
• 555173e fix(where): restore prefix without the old slowdown (beads-ayf)
• cb3ef71 fix: ApplyCLIAutoStart respects ServerModeExternal (#3473)
• 57ddb0b fix: bd admin commands fail with 'embedded mode' error in server mode (#3438)
• eef21de fix: remove duplicate wisp query in bd export (#3352) (#3372)
• 5a2fc61...

beads v1.0.3

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (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

• 72b6cf0 feat(gate): add 'bd gate create' for ad-hoc blocking gates (#3257)
• 8b691be feat(prune): add bd prune for deleting closed non-ephemeral beads (#3353)
• 8518e71 feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393)
• 0d4b979 feat: JSON schema contract, bd ping, structured errors, import enhancements (#3368)
• 34a580c feat: add --exclude-label flag to bd ready and bd list
• 73d72ec feat: add --remote flag to bd dolt push/pull commands (#3211)
• a54ab6f feat: add starter formula examples (#3248)
• 5715f54 feat: make CGO_ENABLED=0 the blessed go install path (GH#3303)
• a78e583 feat: support Unix domain sockets for Dolt server connections (#3300)

Bug Fixes

• 397eb4d fix(ado): use date-only format for WIQL ChangedDate queries (#3345)
• 7bd9e18 fix(audit): use atomic write to prevent torn lines under concurrent O_APPEND (#3301)
• 0dce51a fix(autopush): bound auto-push, throttle failed attempts (#3370) (#3381)
• 80255b6 fix(bootstrap): clone via SQL server in external server mode (#3346)
• 813fdfa fix(ci): unblock main — gosec G122 + credentials_test signatures (#3389)
• 165bd6e fix(config): default Dolt database name when metadata.json is missing (#3380)
• 66da480 fix(config): reject issue-prefix config set
• 5affdbe fix(doctor): resolve Dolt password/TLS for externally-hosted servers (#3361)
• d57dc71 fix(dolt): auto-recover from corrupt manifest on startup (GH#3290) (#3327)
• be8edaa fix(dolt): bd dolt status recognizes externally-hosted Dolt servers (#3362)
• 456a660 fix(dolt): disable auto-push by default; require explicit opt-in (#3446)
• 395935b fix(dolt): exit 0 when push/pull finds no remote configured (GH#3031) (#3194)
• add1759 fix(dolt): pre-push integrity check via dolt fsck (#3447)
• f990135 fix(export): add _type discriminator to JSONL issue lines (#3272)
• d0f0ad6 fix(export): scrub git hook env and skip cross-worktree git-add (GH#3311) (#3347)
• bc74f7e fix(fetch): run GC after failed DOLT_FETCH to prevent tmp_pack_* accumulation (#3326)
• 5b4b8a5 fix(formula): auto-register custom types used by formula gate steps (#3214)
• 6681fdc fix(formula): carry step metadata through cook and pour (GH#3341) (#3359)
• fef7391 fix(gate): keep dry-run checks write-free
• 5c4362d fix(hooks): preserve husky v8/v9 hook layout when copying to .beads/hooks/ (#3197)
• c6d0cc2 fix(init): refuse --force when remote has Dolt history (#3455)
• 3c6c9db fix(init): skip hooks during from-jsonl bootstrap commit (#3342)
• c446a2e fix(linear): harden push against data clobbering (#3328)
• 4e3dbb6 fix(nix): update vendorHash after dependabot go.sum bumps (GH#3221) (#3297)
• 9db6b56 fix(schema): repair v0.63→v1.0 upgrades where issues.started_at is missing (GH#3363) (#3365)
• 39ee50d fix(setup): add alwaysApply frontmatter to Cursor rules template (GH#3191) (#3193)
• e312332 fix(setup): skip duplicate hooks when beads plugin is installed (GH#3192) (#3196)
• baf73a6 fix(worktree): don't prefer inherited .beads/ over shared fallback (#3425)
• dbf793f fix: auto-sanitize hyphenated dolt_database on embedded-mode upgrade (#3231) (#3232)
• e585a61 fix: avoid false shared-server bootstrap no-op for synthesized worktrees
• 43c1dca fix: bd config set --db now resolves BEADS_DIR for yaml-only keys (#3348) (#3379)
• dfde51f fix: bd dolt pull fails when remote added without branch tracking (#3443)
• 98173b0 fix: bd list --parent no longer echoes parent when it has no children (#3349) (#3374)
• 2c0fa6e fix: bd update --type honors custom types (fixes #3030) (#3093)
• 0e09598 fix: cross-rig prefix routing for issue resolution via routes.jsonl (#2954)
• 1e76efc fix: don't normalize user-provided sync.remote URLs (GH#3339) (#3432)
• 0271720 fix: linear tracker reads yaml-only config keys from config.yaml (#3315)
• a0c00d9 fix: make beads-mcp shared-worktree aware
• 27e9a85 fix: no-git-ops=true now implies export.git-add=false (#3314) (#3376)
• a42eded fix: pass CLI filters through tree mode recursive walk (#3384)
• ffe69aa fix: promote gate to built-in type so formula pour works (#3382)
• 3c67e86 fix: rebind selected workspace before db command startup (#3230)
• 0d7f87c fix: remove duplicate database name helper (bd-rrt)
• 7516a39 fix: remove orphan detection from compat migration hot path (#3344) (#3378)
• 6bda86f fix: show (none) placeholder when description is empty in bd show (#3336) (#3375)
• 8abad91 fix: skip DOLT_COMMIT when compat migrations produce no changes (#3366) (#3373)
• 20b9ed7 fix: support Jira Cloud token pagination (#3456)
• 5aa4eb7 fix: use routed ID resolution in bd comments (#3385)
• 5f0be23 fix: warn on unrecognized config keys in bd config set (#3293) (#3377)
• f368f98 fix: wire embedded backend compat migrations by relocating runner (#3413)

Others

• b76947f /.github/workflows/ci.yml: update comment
• c486c7d /default.nix: update vendor hash
• c129725 /{examples,go.mod}: bump go
• 74ad124 Add ADO round-trip integration tests and config documentation (#3305)
• 3906581 Add Linear round-trip fidelity integration test (upstream #3187) (#3255)
• 6e506b6 Add PR preflight and contributor intake guidance (#3470)
• cfdb75e Fix git-remote-cache tmp_pack file leak in embedded mode (#3355)
• 55625db Fix worktree-aware config.yaml resolution (#3265)
• abf03e1 Keep regular epics open after the last child closes (#3276)
• 1b2dd2c Release 1.0.3
• df25aa9 Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291)
• ac085df Skip Dolt remote registration for plain git source repos during init (#3357)
• 04ec3f5 Tier embedded Dolt CI for PRs (bd-0gz) (#3459)
• 578524c [codex] Diagnose Dolt journal corruption and init lock hangs (#3457)
• 63a24bc [codex] Share epic DB setup in one suite (#3296)
• 3f866c0 add Thread to community tools - analytics and observability (#3329)
• 2ade22e chore(build): codify the gms_pure_go build-tag policy (GH#3303)
• a6152f7 chore(deps): bump actions/checkout from 4 to 6 (#3320)
• 5a51e33 chore(deps): bump actions/upload-pages-artifact from 4 to 5 (#3318)
• 37d30f2 chore(deps): bump charm.land/lipgloss/v2 from 2.0.2 to 2.0.3 (#3325)
• 632839c chore(deps): bump fastmcp from 3.2.3 to 3.2.4 in /integrations/beads-mcp (#3319)
• 8b5d546 chore(deps): bump github.com/anthropics/anthropic-sdk-go (#3322)
• e4f0738 chore(deps): bump go.opentelemetry.io/otel/exporters/stdout/stdoutmetric (#3323)
• e3c26c6 chore(deps): bump golang.org/x/term from 0.41.0 to 0.42.0 (#3324)
• cf42092 chore(deps): bump pydantic in /integrations/beads-mcp (#3321)
• 4c240fc chore(gitignore): ignore .codex marker and .claud...

beads v1.0.2

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

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

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

Changelog

Others

• a3f834b release: beads v1.0.2 — npm provenance URL fix

beads v1.0.1

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/steveyegge/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

• 7f0a165 feat(docs): version Docusaurus site and align llms-full with snapshots (#3033)
• f03d4e7 feat(issues): add started_at timestamp (GH#2796) (#3206)
• 3fa1038 feat(telemetry): add pool metrics for shared-server diagnosis (GH#3140) (#3172)
• e39f041 feat: add 'bd batch' for atomic multi-op transactions (#3165)
• cc1cb9e feat: add 'bd config drift' and 'bd config apply' commands (#3086)
• d802687 feat: add --issues flag, push pull subcommands, and --parent port (#2975)
• f5ae2fc feat: add --label and --label-any filtering to bd orphans (#3026)
• ef621e5 feat: add IssueIDs filter to SyncOptions for selective sync (#2957)
• 4bce933 feat: add OpenBestAvailable to public API (#3143) (#3149)
• 2c295f0 feat: add bd config show with unified provenance view (bd-934) (#3084)
• fa87dd2 feat: add global beads_global database for shared-server mode
• e4fca03 feat: add migration test harness for cross-era upgrade fidelity (#3067)

Bug Fixes

• ebcb901 fix(bootstrap): commit issue_prefix to config table (GH#3216) (#3247)
• 4aa573d fix(bootstrap): write metadata.json and config.yaml after sync clone (#3203)
• df2078b fix(ci): collapse multiline expression in cross-version-smoke workflow (#3189)
• 94992a2 fix(ci): correct action versions in cross-version smoke workflow
• 66af622 fix(ci): drop ICU linkage from test jobs, use -tags gms_pure_go everywhere (#3240)
• ec95e7c fix(ci): memoize bd test binary to avoid macOS 10m timeout (#3273)
• 530ffbc fix(ci): remove BEADS_TEST_MODE override and add gms_pure_go tag in migration-test (#3106) (#3108)
• 9211e73 fix(ci): remove Microsoft apt repos before apt-get update (#3224)
• e3a3bb9 fix(ci): resolve lychee baseUrl mismatch with symlink-based root directory (#3105)
• d5d42bf fix(config): honor BEADS_DIR for YAML-only config file resolution (#3104)
• 7fe590d fix(docs): repair broken links failing Deploy Documentation CI (#3103)
• cace7c5 fix(dolt): pass branch to DOLT_PULL to match DOLT_PUSH behavior (#3137)
• 3c7dec4 fix(dolt): reject empty database name in embeddeddolt.New (GH#3113) (#3179)
• f9ec985 fix(dolt): resolve shared-server CLI dir from shared root (#3223)
• 9fa62ee fix(doltserver): rotate dolt-server.log at startup to cap size (#3161)
• 4e0a654 fix(gitlab): wire issue link dependencies into sync pull (GH#2645) (#3202)
• bc613d8 fix(hooks): sanitize husky hooks when copied into beads-managed dir (GH#3132) (#3208)
• f3d4293 fix(init): sanitize dots in metadata.json DoltDatabase and add early validation (#3129)
• 7ada790 fix(list): emit informative truncation hint in all output modes (GH#3212) (#3243)
• 129c3ea fix(mcp): detect Dolt-backed projects in workspace discovery (GH#2997) (#3207)
• e85475d fix(mcp): widen DependencyType to str so all bd dep types validate (#3133)
• 01a3767 fix(mol): use word-boundary regex in distill applyReplacements (#3157)
• 2520c2b fix(nocgo): correct --mode flag in store_factory_nocgo.go error messages (bd-ruk) (#3010)
• b404538 fix(npm): close download streams in postinstall (#3228)
• 696ed0e fix(update): set status=deferred when --defer is provided (GH#3233) (#3241)
• f58bd1d fix: add embeddeddolt/ to .beads/.gitignore template (GH#2994) (#2998)
• 8269ab7 fix: add gms_pure_go tag to linux-amd64 build to remove ICU runtime dep (#2991)
• cadf02e fix: add worktree fallback to countExistingIssues
• e46318e fix: address PR review — replace hardcoded version 23 with LatestVersion()
• 7b02edd fix: allow cross-prefix dependency targets in bd dep add/remove
• a58149d fix: auto-commit config table writes in remember, forget, and config commands (bd-g8p) (#3052)
• 9ab8a79 fix: auto-import issues.jsonl on empty embedded database after upgrade (#2999)
• d46a84b fix: avoid nil-pointer panic in bd dolt pull (embedded mode) (#3148)
• c98e1e7 fix: backfill empty custom_types and custom_statuses tables (#3012)
• 5b53faa fix: backward-compatible JSONL import for all pre-v1.0 formats
• ed91503 fix: backward-compatible JSONL import for all pre-v1.0 formats (#3021)
• f3c1551 fix: bootstrap respects shared-server mode for database path (#3016)
• eee8514 fix: bootstrap uses parent workspace db name when local .beads missing (#3029) (#3083)
• 05734b2 fix: commit test data and use --from-jsonl for JSONL recovery in smoke test
• e54bc62 fix: correct 'bd config' hints to 'bd config set' in error messages (#3141)
• dee815a fix: custom status and type validation falls back to config when tables are empty
• 22aacc3 fix: custom status validation falls back to config when table is empty (#2985)
• ebbf720 fix: detect transitive dependency cycles in bd mol bond (#2719) (#3111)
• 64e504d fix: enable auto-export by default and add init prompt (GH#2973) (#3204)
• 31d5123 fix: ensure wisp tables exist after bootstrap clone
• 1a218aa fix: explicitly disable TLS in Dolt connections when not configured (#3107)
• afbfcbe fix: export JSONL in pre-commit hook for atomic code+issues commits (#3121)
• af12d6f fix: export data before clearing metadata in server→embedded migration (#3075)
• a3b323d fix: fall through to config string when custom_statuses table is empty
• d49c503 fix: gate doctor tests on container port, not env var (GH-3087)
• 4bdf39e fix: handle JSON array format in SyncCustomTypesTable
• 63770b6 fix: handle read-only Go module cache files in test temp dir cleanup
• b599839 fix: handle release archives that extract into a subdirectory (#3167)
• 15f8a14 fix: harden bootstrap database naming and reject empty db param (GH#3029)
• 05a9069 fix: include comment bodies in bd export JSONL output
• ad285ad fix: include comment bodies in export and fix same-second dedup on import (#3009)
• a3923ed fix: narrow cross-version smoke CI triggers and warn on high skip rate
• 23bfd05 fix: parse create output for versions without --silent flag
• 8d94faf fix: preserve dependencies and labels in SQLite-era JSONL migration (#3079) (#3082)
• f0adda4 fix: prevent silent fallback to embedded mode when shared-server is active (GH#2949)
• f700796 fix: proper failure reporting for cross-version smoke test
• 98d8e72 fix: queue concurrent embedded Dolt callers instead of failing (#3005)
• 7916e02 fix: remove ICU runtime dependency from release binaries (#3066)
• 8ccb82d fix: remove duplicate testutil import in validation_test.go
• 9d0b7ad fix: remove nonexistent -i flag from bd import references (#3200)
• 70e1596 fix: remove redundant os.Stat check after FindBeadsDir
• 6686e1d fix: remove set -e to prevent dolt server crashes killing the script
• c911055 fix: remove stale worktree guard in rename-prefix
• 164e251 fix: remove unsupported stepping-stone migration paths (#3073) (#3110)
• 5d9e878 fix: replace CWD-only ch...

beads v1.0.0

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/steveyegge/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

• 5e60961 feat(init): add --non-interactive and --role flags for CI/cloud agents
• 29531d2 feat: GitLab sync — dedup fixes, type filtering, epic→milestone mapping, work item hierarchy (#2889)
• 7806fbf feat: add --non-interactive flag to bd bootstrap for CI (#2942)
• 677f7bc feat: add SlotSet/SlotGet/SlotClear to Storage interface (#2870)
• c46be6e feat: add bd config set-many for batch config operations (#2943)
• 4d88e4a feat: add public format package for issue rendering (#2871)
• 08ee138 feat: add spike, story, and milestone as first-class issue types (#2923)
• 9b90ada feat: export WispFilter type from root package (#2868)
• 8537d94 feat: migrate custom statuses and types to normalized tables (#2961)
• 73409d5 feat: move hook firing into storage layer via decorator (#2891)
• dc39fdc feat: support batch dep list for multiple issue IDs (#2875)
• bf4025b feat: support comma-separated status values in bd list --status (GH#2846) (#2929)

Bug Fixes

• d56bf01 fix(ado): apply --types/--states/--no-create filters to push operations (#2944)
• 9e34b07 fix(ado): create work items in initial state then transition to target
• 20b39b3 fix(deps): migrate from lipgloss v1 to charm.land/lipgloss/v2
• dc398f5 fix(deps): update github.com/yuin/goldmark to v1.8.2
• 30cb4a5 fix(deps): update module github.com/cenkalti/backoff/v4 to v5 (#2857)
• 933253e fix(dolt): add recovery guidance for diverged history errors (#2941)
• ead8d09 fix(gitlab): resolve hardcoded work item type ID and O(n) milestone scan
• a44d4f9 fix(init): replace 'bd onboard' references with 'bd prime' in AGENTS.md (#2902)
• 41001f7 fix(install): redirect log functions to stderr to fix WSL platform detection
• 5e751f8 fix(lint): suppress gosec G122 false positive in noms LOCK cleanup
• 999f875 fix(test): remove tautological TestRoleFlagValidation
• 59b49c4 fix: add missing //go:build cgo tags to embedded test files and cmd
• 8725226 fix: add missing created_at index on wisp_events (GH#2760) (#2877)
• 1f4863b fix: add whitespace trimming to env var parsing in IsAutoStartDisabled (#2955)
• 2cd88e9 fix: address PR review feedback
• 63c7a26 fix: adopt existing project_id when init --database targets shared server (#2925)
• 685cb84 fix: bd bootstrap detects remote data in fresh clones (GH#2792)
• bbc8128 fix: bump currentSchemaVersion to 11 for custom_statuses/custom_types tables
• dbdc955 fix: clean stale noms LOCK files after bootstrap clone (bd-cmo)
• dfa54aa fix: configure link checker root dir for docusaurus deploy
• a2fc789 fix: make --yes/-y the primary flag in bd bootstrap, --non-interactive as alias
• 223895b fix: make bd setup claude project-local by default and auto-setup in bd init (#2935) (#2972)
• 0a1be38 fix: pass parent env vars to dolt-sql-server child process
• 4e4d958 fix: prefer bootstrap for missing database recovery (#2940)
• 2a71d7f fix: preserve spaces in embedded Dolt paths
• 543e194 fix: prevent concurrent embedded Dolt panic with exclusive flock (#2571)
• 33cab03 fix: recognize ado:NNNNN shorthand in IsExternalRef and ExtractIdentifier (#2966)
• 37382b0 fix: remove bogus //nolint:gosec G122 directive (rule does not exist)
• 870cb83 fix: remove dead rig routing code and unused variable after rebase
• ba46bd5 fix: repair nightly test failures for TestInitCancel_E2E and dolt autostart (#2969)
• ae77bd4 fix: replace fragile string matching with typed APIError for HTTP status checks
• 163c27b fix: set ADO Severity field for Bug work items during sync
• 29bef78 fix: show blocked icon for dependency-blocked issues in bd list (#2858) (#2878)
• 265de3c fix: skip E2E test that requires Dolt server in embedded mode (#2888)
• a097723 fix: suppress auto-backup address conflict warning (#2927)
• baa9d02 fix: treat --shared-server as server mode for DoltMode (#2947)
• 9d9d0e5 fix: unwrap HookFiringStore decorator before optional interface type assertions (#2937)
• c174416 fix: update goreleaser owner to gastownhall (repo moved from steveyegge)
• 36e063d fix: update workflow gates from steveyegge/beads to gastownhall/beads (#2936)
• 299b5f6 fix: use ResolveCustomTypesInTx in create path to honor YAML custom types (GH#2793) (#2930)
• 8cd2476 fix: use proper RFC3339 timezone in WIQL date formatting (bd-wz8)
• 9f3b813 fix: use strconv.ParseBool for env var parsing in IsAutoStartDisabled (#2956)
• ca67253 fix: validate graph plan node types against custom types (#2874)

Others

• 15f9696 /cmd/bd/doctor: formatting
• d326a27 /{.github,.goreleaser}: enable embedded by default on mac (#2971)
• 44c764e /{cmd,docs,internal}: more cleanup
• f1bf098 /{cmd,docs,internal}: remove file removal that can cause data corruption
• 4191643 Add --explain flag to bd ready for dependency-aware reasoning
• 5d524cf Add Integration Charter: define scope boundary for tracker integrations
• 6863ca7 Add bd rules audit and bd rules compact commands (#2810)
• bbd6c41 Add claude-workspace-snapshot to Claude Code Orchestration
• 7e4da9a Add credentials file support for Dolt server passwords (#2854)
• 2efa094 Add integration test coverage for partial failures, warnings, and self-deps
• c5e033f Add pagination guards to Linear and context checks to Jira client
• 9d7882c Add release stability gate for upgrade safety (GH#2951) (#2963)
• 00b78da Add retry logic to Jira client and jitter to all tracker HTTP clients
• 047e506 Enforce .beads/ directory permissions at runtime
• 0383ad7 Enforce graph integrity: extend cycle detection and add bd graph check
• ac4ee4a Expand SECURITY.md with tracker integration trust model
• 5708a36 Fix ADO Init tests leaking environment variables
• ca1ae15 Fix init leaving beads.role unset in edge cases (GH#2950) (#2964)
• 5588033 Improve compaction dry-run and analyze output with per-issue details
• 917c5f6 Improve quickstart docs with Why Beads section and --explain examples
• 733b8fa Sanitize external tracker content for terminal display and add response size limits
• 8d41e70 Surface sync engine warnings in SyncResult and fix silent failure paths
• dbcc2db [codex] Fix installer ICU/CGO fallback handling (#2965)
• d15b448 chore(deps): bump charm.land/lipgloss/v2 from 2.0.1 to 2.0.2 (#2919)
• d02f1f9 chore(deps): bump fastmcp from 3.1.1 to 3.2.0 in /integrations/beads-mcp (#2918)
• 7217026 ci: fix macOS smoke test temp dir with dots in name
• edb6f58 ci: retrigger after flaky Dolt lock contention in TestEmbeddedInit
• ad53f30 cmd/bd: honor explicit repo selection for no-db commands (#2844)
• 73f786f github,ado: fix Retry-After jitter in retry loops
• 82c2890 jira: add MaxPages pagi...

beads v0.63.3

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

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

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

Changelog

Bug Fixes

• b706786 fix(beads): detect embeddeddolt/ directory in database discovery (#2909)
• 884cc11 fix(release): revert all non-Linux targets to CGO_ENABLED=0, bump v0.63.3
• 97889d9 fix: include convoy-type formulas in bd formula list text output

beads v0.62.0

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/steveyegge/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

• 6724965 Merge PR #2638: feat: add --format json alias for --json flag
• 39ab50d feat(ado): add Azure DevOps work item tracker package
• 9f5741f feat(ado): add bd ado CLI commands (sync, status, projects)
• 9a8aa55 feat(embeddeddolt): add embedded Dolt support for dep, duplicate, epic, graph, supersede, swarm (fix-merge PR #2734)
• a44ecef feat(init): default AGENTS.md to minimal profile, add --agents-profile flag
• 5f2d433 feat: add 'bd note' command as shorthand for appending notes
• affb314 feat: add --exclude-type flag to bd ready and bd list
• d6e5a5f feat: add --format json alias for --json flag
• faa69f9 feat: audit log captures close reason; add v0.62.0 changelog and version notes
• a44e01e feat: audit log status changes to interactions.jsonl (bd-42f)
• 9b2c012 feat: custom status categories (active/wip/done/frozen)
• fab29b0 feat: expose issue_type filter on MCP ready tool (PR #2660)
• a22af2d feat: include memories in export/import round-trip
• 0fe9c03 feat: surface quality/lifecycle commands in prime, template, and doctor (fix-merge PR #2664)

Bug Fixes

• 679d7bf Merge PR #2651: fix: use go run for golangci-lint in pre-commit hook
• ae28719 fix(ci): add write permissions to update-flake-lock workflow (PR #2642)
• c847353 fix(cli): keep repo .beads config when dolt_data_dir escapes
• e566d3a fix(config): route config unset to correct store (GH#2727)
• 4a5cb16 fix(deps): update dolthub/driver v0.2.1 to v1.83.8 (fix-merge PR #2720)
• e6ee4f9 fix(deps): update github.com/anthropics/anthropic-sdk-go to v1.27.1 (PR #2705)
• 51d41e2 fix(deps): update github.com/dolthub/driver digest to 1f97424 (PR #2650)
• 164cea7 fix(doctor): add dolt-server.activity to gitignore, prioritize gitignore fixes (GH#2723)
• c3ee79e fix(doctor): fail closed for server-mode integrity recovery
• e2f9f51 fix(dolt): bump schema version to 8 and commit version update (PR #2635)
• 87c8985 fix(dolt): keep repo-local auto-started servers alive across commands
• 60dd444 fix(dolt): verify dolt_status is clean after schema upgrade (GH#2634)
• 71a0360 fix(hooks): increase shim timeout from 30s to 300s for chained hooks (GH#2732)
• ec18969 fix(init): add .beads-credential-key to project-root .gitignore (GH#2695)
• 8225a14 fix(init): add TTL to circuit breaker state and clean stale files during init
• 0423e25 fix(mol): add cycle detection to bond traversal to prevent OOM (GH#2719)
• f8152a1 fix(update): require explicit opt-in for empty stdin/file DESCRIPTION rewrites
• 63432ac fix: --validate checks --acceptance field, add validation.on-close config (PR #2654)
• 468c863 fix: Windows Dolt server lifecycle — stale state files and false auto-stop warning (GH#2670)
• ecf15d9 fix: add .beads-credential-key to .gitignore template (PR #2681)
• f535a18 fix: add no_history column to embedded Dolt base schemas (PR #2632)
• 5b9e65d fix: add retry loop for Windows binary existence check after zip extraction (fix-merge PR #2753)
• e650b1f fix: add warnings for silent database name fallback in main command path
• e67a574 fix: bootstrap imports from git-tracked .beads/issues.jsonl
• fabda03 fix: check BEADS_DOLT_SERVER_DATABASE env var in applyConfigDefaults
• 2846af3 fix: correct bd human help text for adding comments (fix-merge PR #2752)
• 0e13cb5 fix: correct version ordering in versionChanges (PR #2633)
• 2aff244 fix: don't kill externally-managed dolt servers (GH#2641)
• d56d290 fix: drop id from ORDER BY in GetAllEventsSince UNION ALL query (PR #2691)
• f20b3d0 fix: load .beads/.env before noDbCommands early return
• 93bfd45 fix: load .beads/.env before noDbCommands early return (GH#2677)
• fe1c9d5 fix: make KillStaleServers respect server ownership
• b70f740 fix: mark unused cfg param in checkProjectIdentityNoStore
• 2db73f8 fix: merge duplicate v0.60.0 changelog entries into single block
• b272e0b fix: pass repo path through fingerprint check to fix merge with main
• 76bfcd3 fix: preserve all hooks when overriding core.hooksPath, not just managed ones
• a153b13 fix: preserve pre-existing hooks when bd init sets core.hooksPath
• c75c2b5 fix: prevent doctor infinite Dolt server restart loop (GH#2636)
• a683dbc fix: prevent silent fallback to default "beads" database in openDoltDB
• 332f641 fix: remove duplicate TestCompactTier1_DryRun (PR #2631)
• 6468766 fix: remove hardcoded ~/gt/ paths from beads codebase (bd-h615)
• 059ee44 fix: remove unnecessary type conversions in find_duplicates.go
• cb98259 fix: remove unnecessary type conversions in find_duplicates.go
• f442c08 fix: remove unnecessary type conversions in find_duplicates.go
• b89f1b3 fix: remove unnecessary type conversions in find_duplicates.go
• e88379f fix: remove unnecessary type conversions in haiku.go
• 1142460 fix: remove unnecessary type conversions in haiku.go
• 32d4178 fix: remove unnecessary type conversions in haiku.go
• 95dfaf0 fix: remove unnecessary type conversions in haiku.go
• 43df89b fix: repair nightly integration test compilation failures
• dc180dd fix: replace broken SQL CAST in GetNextChildIDTx with Go-side parsing (GH#2721)
• bcfa8a7 fix: resolve --format json collision between rootCmd persistent flag and list/dep-tree local flags
• f73a9ca fix: serialize concurrent initSchemaOnDB with GET_LOCK to prevent journal corruption (#2672)
• 21fe42e fix: suppress gosec G304 for filepath.Glob-sourced path in circuit breaker cleanup
• c9d7730 fix: update test_stats fixture to match nested Stats model (PR #2659)
• 811d736 fix: use SHOW COLUMNS in uuid_primary_keys migration to avoid server-mode crash (fix-merge PR #2751)
• c4fbe1e fix: use SQL stored procedures for bd flatten/compact in server mode (bd-uty)
• 6d1777a fix: use go run for golangci-lint in pre-commit hook

Others

• 02c59bc /.github/workflows/ci.yml: skip build step
• 4523b77 /cmd/bd/count_embedded_test.go: count tests
• 778975c /cmd/bd/diff_embedded_test.go: diff tests
• 44a95b3 /cmd/bd/find_duplicates_embedded_test.go: test
• 70e7d9e /cmd/bd/gate_embedded_test.go: gate test
• 18136bc /cmd/bd/init_embedded_test.go: fix test
• 4b26c76 /cmd/bd/label_embedded_test.go: add label tests
• 5b9546c /cmd/bd/list_embedded_test.go: formatting
• 555f4b5 /cmd/bd/merge_slot_embedded_test.go: merge slot
• e7a4922 /cmd/bd/move_embedded_test.go: move slot
• 9273ddf /cmd/bd/promote_embedded_test.go: promote test
• 01c193e /cmd/bd/query_embedded_test.go: add query test
• 2163689 /cmd/bd/quick_embedded_test.go: quick test
• ed6551d /cmd/bd/search_embedded_test.go: search test
• 06be1de...

beads v0.61.0

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/steveyegge/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

• ad0417a Merge PR #2543: feat(dolt): CLI credential pass-through for server mode push/pull
• ef59bd0 Merge PR #2585: feat: auto-detect beads database on git origin during init/bootstrap
• 947d557 Merge PR #2594: feat: add --claim-next to close and --skills/--context to create
• 22ab742 Merge PR #2600: feat: prime SSOT tasks 8-12 — init upgrade, recipe cleanup, symlink safety, staleness detection
• ee4dc91 Merge PR #2600: feat: prime SSOT tasks 8-12 — init upgrade, recipe cleanup, symlink safety, staleness detection
• de5f0b9 Merge PR #2622: feat: add --no-history flag to separate Dolt commit skipping from GC eligibility
• 5689f48 feat(dolt): add CLI credential routing for federation PushTo/PullFrom/Fetch
• 02dc8c8 feat(dolt): add CLI credential routing for server mode push
• 1911d2d feat(dolt): extend CLI credential routing to ForcePush and Pull
• 6edd905 feat(setup): target CLAUDE.md and GEMINI.md for hooks integrations
• 7267cbb feat(setup): target CLAUDE.md and GEMINI.md for hooks integrations
• 93b8529 feat: Claude and Gemini setup install minimal AGENTS.md section (#2139, tasks 5-6)
• 6588c53 feat: Claude and Gemini setup install minimal AGENTS.md section (#2139, tasks 5-6)
• 1ce765e feat: UUID primary keys for federation-safe events
• ecad137 feat: add --claim-next to close and --skills/--context to create
• 869cc17 feat: add --no-history flag to bd create — skip Dolt commits without GC eligibility
• 6673026 feat: add --skip-agents flag and branchless/JJ docs (GH#1335)
• 04799bc feat: add bd import command for incremental JSONL import
• 4d14fb8 feat: auto-detect beads database on git origin during bootstrap
• 05142d0 feat: consolidate prime SSOT section replacement into canonical ReplaceSection (bd-jfe5)
• f79ba31 feat: explicit profile:full on all AGENTS.md integrations (#2139, task 4)
• d115e93 feat: explicit profile:full on all AGENTS.md integrations (#2139, task 4)
• 46816ee feat: prime SSOT tasks 1-3 — shared render API, template profiles, prefix-aware parser (#2139)
• f78b1b2 feat: prime SSOT tasks 1-3 — shared render API, template profiles, prefix-aware parser (#2139)
• a0720f2 feat: prime SSOT tasks 8-12 — init upgrade, recipe cleanup, symlink safety, staleness detection (#2139)
• 809bd43 feat: prime SSOT tasks 8-12 — init upgrade, recipe cleanup, symlink safety, staleness detection (#2139)

Bug Fixes

• 52c9dea Merge PR #2537: fix: respect BD_BACKUP_ENABLED=false to suppress backup commits (GH#2534)
• 91d98f3 Merge PR #2538: fix: bd doctor detects committed runtime/sensitive files (GH#2535)
• 259925c Merge PR #2564: fix(flake): Go 1.25.8 overlay + vendorHash for nix build and devShell
• 17ca46d Merge PR #2567: fix(embeddeddolt): implement more storage methods
• 4a1a7f9 Merge PR #2578: fix: formula extends merges child steps by ID instead of appending
• a39ee2b Merge PR #2578: fix: formula extends merges child steps by ID instead of appending
• 3d1f844 Merge PR #2579: fix(deps): update github.com/dolthub/driver digest to 0fe74e7
• 76b102c Merge PR #2582: fix: allow colons in unquoted query identifier values
• fcef544 Merge PR #2586: fix(doctor): auto-start Dolt on cold standalone checks
• 7017954 Merge PR #2591: fix: applyConfigDefaults uses full port resolution chain
• 62f310c Merge PR #2592: fix: read jira.pull_jql config during FetchIssues
• 393b082 Merge PR #2593: fix: scope KillStaleServers to repo own data directory
• c748838 Merge PR #2597: fix: complete UUID primary keys cleanup
• 82f6a81 Merge PR #2603: fix(deps): update dependency fastmcp to v3.1.1
• 549345f Merge PR #2604: fix: key circuit breaker on host:port instead of port only
• 3436b7c Merge PR #2607: fix(doctor): detect server-backed runtime for concurrency check
• b7ff054 Merge PR #2610: fix(backup): accept UUID comment and event IDs during restore
• 0601fff Merge PR #2616: fix(doctor): use target repo for fingerprint checks
• 66057e6 Merge PR #2618: fix: store credential key in .beads/ to avoid ghost dolt directories
• 81fcf44 fix(deps): update dependency fastmcp to v3.1.1
• 190e70f fix(deps): update github.com/dolthub/driver digest to 0fe74e7
• bc28d83 fix(doctor): auto-start Dolt on cold standalone checks
• ebff84d fix(doctor): detect server-backed runtime for concurrency check
• 65ed43f fix(doctor): honor bare-parent beads dir for gitignore repair (beads-9f74-q9o)
• 9f3603b fix(doctor): honor bare-parent fallback in dolt lock checks (beads-9f74-f5e)
• 94a5524 fix(doctor): use effective beads dir for shared-server checks (beads-9f74-385)
• 66079fd fix(flake): overlay Go 1.25.8 for devShell compatibility
• f320e3c fix(flake): override go_1_25 and fix vendorHash
• fd17ed1 fix(init): warn when server host defaults to localhost
• bb45595 fix: Commit() excludes config table to prevent issue_prefix corruption (GH#2455)
• e9bce23 fix: EnsureRunning skips Start() when explicit port indicates external server
• 2fea62f fix: accept UUID comment and event IDs during restore
• 273c377 fix: add timeout and prompt suppression to git ls-remote probe
• 4856644 fix: allow colons in unquoted query identifier values
• 1b7bb92 fix: applyConfigDefaults uses full port resolution chain
• a45961c fix: bd context reports actual runtime Dolt port instead of default 3307
• 350c050 fix: bd doctor detects committed runtime/sensitive files that should be gitignored (GH#2535)
• d3cf4e9 fix: bd init fails in directories starting with a dot
• 3024c09 fix: bd list ready rejects bare keyword with hint to use --ready (GH#2532) (#2536)
• 7bbd928 fix: clean stale noms LOCK files before opening embedded dolt store
• fca3d3c fix: complete UUID primary keys cleanup across codebase
• cba968e fix: detached commit worktree test fails when default branch is not main
• f286e39 fix: formula extends merges child steps by ID instead of appending
• c36b4ed fix: gofmt import.go and update stale embedded dolt from_jsonl test
• 97fb20b fix: handle BEADS_DB pointing to directory instead of file
• c5cb9f6 fix: handle BEADS_DB pointing to directory instead of file (#2549)
• 3158495 fix: key circuit breaker on host:port instead of port only (bd-ic2)
• 1bb721c fix: make --title, --title-contains, --desc-contains case-insensitive
• c51923d fix: merge user-level config under project config instead of ignoring it (GH#2375)
• 0827ccd fix: migrate server-root remotes to database dir on store open (GH#2118)
• b1b11d2 fix: port-0 circuit breaker poisoning prevention (fix-merge PR #2599)
• fb51196 fix: preserve source rig's dolt_database across .beads/redirect
• ef654a9 fix: prevent comment duplication on re-import
• 41de7e0 fix: read jira.pull_jql config during FetchIssues
• 4b2a3b8 fix: repair broken setupDetachedCommitBeadsWorktree test h...

beads v0.60.0

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

Installation

Homebrew (macOS/Linux):

brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/steveyegge/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

• 43bca27 feat: JSON-aware error output + JSONL schema validation + contract tests (GH#2499)
• 71d7ae5 feat: add --design-file flag for reading design from files
• 12dc4e0 feat: add --destroy-token for safe non-interactive re-init (GH#2497)
• 9dc875a feat: add --list and --doc flags to bd help for CLI doc generation (GH#2527)
• 0cf8666 feat: add GitHub Issues integration (tracker plugin) (GH#2373)
• ac9ac70 feat: add bd context command and safe-first error guidance (fix-merge PR #2496)
• 0bb3bf2 feat: add workspace identity preflight and bd bootstrap command (GH#2438, GH#2372)
• efd7568 feat: bd bootstrap executes recovery actions instead of printing advice
• 2df714f feat: bd done treats last arg as reason
• 21e23bc feat: epic close guards, merge re-parenting, and progress display
• b7cc484 feat: replace hash-derived dolt ports with OS-assigned ephemeral ports (GH#2415)
• 5e1d4b9 feat: search external_ref in bd search (GH#2494)
• 3a2d351 feat: support global ~/.config/beads/PRIME.md fallback (GH#2330)

Bug Fixes

• 0c12f46 Merge PR #2390: fix(deps): update github.com/dolthub/driver digest to bbe1450
• dbbe212 Merge PR #2408: fix(worktree): skip .gitignore append when parent directory pattern covers
• c3e7057 Merge PR #2413: fix(deps): update opentelemetry-go monorepo to v1.42.0
• 93841bd Merge PR #2417: fix: bd mol wisp reports wrong count when RootOnly=true
• 3502cb4 Merge PR #2432: fix: use Root().PersistentFlags() to check --json in PersistentPreRun
• 1d25504 Merge PR #2440: fix: replace stale 'bd sync' references in CLI help, setup generators, and docs
• 1ffbd0f Merge PR #2443: fix(list): --json flag ignored when --tree defaults to true
• f1e6073 Merge PR #2529: fix(deps): update github.com/dolthub/driver digest to 669bd7f
• 8130756 fix(deps): migrate glamour to v2 (charm.land/glamour/v2)
• 4c43d96 fix(deps): update github.com/dolthub/driver digest to 669bd7f
• dc0b180 fix(deps): update github.com/dolthub/driver digest to bbe1450
• 555abde fix(deps): update github.com/dolthub/driver digest to ecee5fd
• 7f03975 fix(deps): update module golang.org/x/sync to v0.20.0
• 1a328cb fix(deps): update module golang.org/x/sys to v0.42.0
• db967a0 fix(deps): update module golang.org/x/term to v0.41.0
• 8962de5 fix(deps): update opentelemetry-go monorepo to v1.42.0
• 257c052 fix(deps): update testcontainers-go monorepo to v0.41.0
• a333dca fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
• f7061f9 fix(docs): remove stale --branch flag and SQLite refs from QUICKSTART (GH#2522) (#2525)
• 1fb6b95 fix(dolt): auto-commit pending changes before pull to prevent merge errors (GH#2474)
• c195a5e fix(list): --json flag ignored when --tree defaults to true
• 15a9d16 fix(list): --json flag ignored when --tree defaults to true
• 44118a8 fix(list): --json flag ignored when --tree defaults to true (bd-03r)
• 45fcd51 fix(nix): use go mod edit instead of sed for version patching
• 656a3e5 fix(worktree): skip gitignore append when parent dir pattern already covers entry
• f88c298 fix: Dolt test suite stability — eliminate container crashes and cascading failures (hq-33riy)
• c9998fc fix: TestDoltStoreDependencies uses same-type issues for blocks dep (GH#1495)
• cf9f78d fix: TestProtocol_FieldsRoundTrip timezone-aware date assertions
• 8386380 fix: YAML config prefix takes precedence over DB in shared-server mode (GH#2469)
• 7d06e6c fix: add BEADS_DOLT_PORT fallback in GetDoltServerPort() (GH#2486)
• 396c944 fix: add shared Dolt server mode for multi-repo/agent setups (GH#2416)
• 69573b8 fix: add test coverage for quoted label values with colons (bd-wnr1)
• 1d7bf35 fix: add timeout and graceful DB-missing handling to git hook shims
• d00c310 fix: auto-clear stale pinned flag on status transition
• 0ba22ae fix: auto-resolve metadata merge conflicts on bd dolt pull (GH#2466)
• 401da9d fix: backfill project_id into pre-GH#2372 Dolt stores via bd doctor --fix (GH#2490)
• 9b04d6c fix: bd children includes closed children by default (GH#2481)
• 12cfd5c fix: bd doctor --fix regenerates missing metadata.json (GH#2482)
• 766fe2f fix: bd doctor detects stale .legacy hook sidecars calling removed bd hook (GH#2398)
• 61ddbe3 fix: bd dolt remote add/list/remove operate on wrong directory (GH#2306, GH#2311)
• d1549d9 fix: bd export crash on zero-time timestamps + stale bd sync refs (GH#2488, GH#2493)
• 3dbf3c7 fix: bd lint accepts non-empty acceptance_criteria field without heading (GH#2468)
• c12ccea fix: bd mol wisp reports wrong count when RootOnly=true
• a84f7c3 fix: block bd doctor --fix at Gas Town town root (GH#2450)
• 2c24ce6 fix: block data-dir in server mode + fix doctor --clean --json (GH#2438)
• a5a751f fix: clean formatting drift
• 36a3ecd fix: create .beads/ dir in server mode with external BEADS_DOLT_* env vars (GH#2519)
• fbbaa5e fix: detect WSL and MINGW/MSYS/CYGWIN in install.sh
• eae64ca fix: detect backup files on database-not-found and after bd init (GH#2327)
• 4537e07 fix: exclude reparented children from molecule auto-close (GH#2480)
• e6019d9 fix: hide --allow-stale no-op flag from help output
• e56fc50 fix: idle-monitor preserves port across restart cycles (bd-xvg)
• 9604d30 fix: init guard allows fresh clones with committed metadata.json (GH#2433, GH#2441)
• 9d65ac8 fix: merge --metadata with existing metadata instead of replacing (GH#2423)
• 141119a fix: move KillStaleServers inside flock to prevent journal corruption (GH#2430)
• 4591600 fix: move auto-push state to local file, preventing metadata merge conflicts (GH#2466)
• 5227eab fix: preserve dependency metadata in JSONL backups (GH#2487)
• a7755e5 fix: prevent bd init from creating DB on another project's Dolt server (GH#2336)
• 4df17ca fix: remove idle monitor and activity signal daemon infrastructure (GH#2452)
• 100962f fix: remove stale 'sync' from noDbCommands breaking sync subcommands (GH#2419)
• 3e20e7e fix: replace dangerous --force suggestion in init guard error message
• 31bae5a fix: replace hash-derived dolt ports with OS-assigned ephemeral ports (GH#2415)
• b7bd6d6 fix: replace stale 'bd sync' references with bd dolt push/commit (GH#2435)
• cd2f500 fix: replace stale bd migrate --to-dolt with bd init --from-jsonl (GH#2333)
• bdbbb4b fix: restore --allow-stale as no-op flag for gt compatibility
• de483f4 fix: restore denormalized JSONL from bd export without data loss (GH#2479)
• b515661 fix: skip sleep in CI/non-interactive environments
• 5a454ae fix: suppress pre-existing gosec false positives with nolint directives
• 2d3ce08 fix: sync CLI remotes into SQL server on store open (GH#2315)
• 56cd587...