Beads Files

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

:::bash
brew install beads

Quick Install (macOS/Linux/FreeBSD):

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

Windows (PowerShell):

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

• [7f0a16] feat(docs): version Docusaurus site and align llms-full with snapshots (#3033)
• [f03d4e] feat(issues): add started_at timestamp (GH#2796) (#3206)
• [3fa103] feat(telemetry): add pool metrics for shared-server diagnosis (GH#3140) (#3172)
• [e39f04] feat: add 'bd batch' for atomic multi-op transactions (#3165)
• [cc1cb9] feat: add 'bd config drift' and 'bd config apply' commands (#3086)
• [d80268] feat: add --issues flag, push pull subcommands, and --parent port (#2975)
• [f5ae2f] feat: add --label and --label-any filtering to bd orphans (#3026)
• [ef621e] feat: add IssueIDs filter to SyncOptions for selective sync (#2957)
• [4bce93] feat: add OpenBestAvailable to public API (#3143) (#3149)
• [2c295f] feat: add bd config show with unified provenance view (bd-934) (#3084)
• [fa87dd] feat: add global beads_global database for shared-server mode
• [e4fca0] feat: add migration test harness for cross-era upgrade fidelity (#3067)

Bug Fixes

• [ebcb90] fix(bootstrap): commit issue_prefix to config table (GH#3216) (#3247)
• [4aa573] fix(bootstrap): write metadata.json and config.yaml after sync clone (#3203)
• [df2078] fix(ci): collapse multiline expression in cross-version-smoke workflow (#3189)
• [94992a] fix(ci): correct action versions in cross-version smoke workflow
• [66af62] fix(ci): drop ICU linkage from test jobs, use -tags gms_pure_go everywhere (#3240)
• [ec95e7] fix(ci): memoize bd test binary to avoid macOS 10m timeout (#3273)
• [530ffb] fix(ci): remove BEADS_TEST_MODE override and add gms_pure_go tag in migration-test (#3106) (#3108)
• [9211e7] fix(ci): remove Microsoft apt repos before apt-get update (#3224)
• [e3a3bb] fix(ci): resolve lychee baseUrl mismatch with symlink-based root directory (#3105)
• [d5d42b] fix(config): honor BEADS_DIR for YAML-only config file resolution (#3104)
• [7fe590] fix(docs): repair broken links failing Deploy Documentation CI (#3103)
• [cace7c] fix(dolt): pass branch to DOLT_PULL to match DOLT_PUSH behavior (#3137)
• [3c7dec] fix(dolt): reject empty database name in embeddeddolt.New (GH#3113) (#3179)
• [f9ec98] fix(dolt): resolve shared-server CLI dir from shared root (#3223)
• [9fa62e] fix(doltserver): rotate dolt-server.log at startup to cap size (#3161)
• [4e0a65] fix(gitlab): wire issue link dependencies into sync pull (GH#2645) (#3202)
• [bc613d] fix(hooks): sanitize husky hooks when copied into beads-managed dir (GH#3132) (#3208)
• [f3d429] fix(init): sanitize dots in metadata.json DoltDatabase and add early validation (#3129)
• [7ada79] fix(list): emit informative truncation hint in all output modes (GH#3212) (#3243)
• [129c3e] fix(mcp): detect Dolt-backed projects in workspace discovery (GH#2997) (#3207)
• [e85475] fix(mcp): widen DependencyType to str so all bd dep types validate (#3133)
• [01a376] fix(mol): use word-boundary regex in distill applyReplacements (#3157)
• [2520c2] fix(nocgo): correct --mode flag in store_factory_nocgo.go error messages (bd-ruk) (#3010)
• [b40453] fix(npm): close download streams in postinstall (#3228)
• [696ed0] fix(update): set status=deferred when --defer is provided (GH#3233) (#3241)
• [f58bd1] fix: add embeddeddolt/ to .beads/.gitignore template (GH#2994) (#2998)
• [8269ab] fix: add gms_pure_go tag to linux-amd64 build to remove ICU runtime dep (#2991)
• [cadf02] fix: add worktree fallback to countExistingIssues
• [e46318] fix: address PR review — replace hardcoded version 23 with LatestVersion()
• [7b02ed] fix: allow cross-prefix dependency targets in bd dep add/remove
• [a58149] fix: auto-commit config table writes in remember, forget, and config commands (bd-g8p) (#3052)
• [9ab8a7] fix: auto-import issues.jsonl on empty embedded database after upgrade (#2999)
• [d46a84] fix: avoid nil-pointer panic in bd dolt pull (embedded mode) (#3148)
• [c98e1e] fix: backfill empty custom_types and custom_statuses tables (#3012)
• [5b53fa] fix: backward-compatible JSONL import for all pre-v1.0 formats
• [ed9150] fix: backward-compatible JSONL import for all pre-v1.0 formats (#3021)
• [f3c155] fix: bootstrap respects shared-server mode for database path (#3016)
• [eee851] fix: bootstrap uses parent workspace db name when local .beads missing (#3029) (#3083)
• [05734b] fix: commit test data and use --from-jsonl for JSONL recovery in smoke test
• [e54bc6] fix: correct 'bd config' hints to 'bd config set' in error messages (#3141)
• [dee815] fix: custom status and type validation falls back to config when tables are empty
• [22aacc] fix: custom status validation falls back to config when table is empty (#2985)
• [ebbf72] fix: detect transitive dependency cycles in bd mol bond (#2719) (#3111)
• [64e504] fix: enable auto-export by default and add init prompt (GH#2973) (#3204)
• [31d512] fix: ensure wisp tables exist after bootstrap clone
• [1a218a] fix: explicitly disable TLS in Dolt connections when not configured (#3107)
• [afbfcb] fix: export JSONL in pre-commit hook for atomic code+issues commits (#3121)
• [af12d6] fix: export data before clearing metadata in server→embedded migration (#3075)
• [a3b323] fix: fall through to config string when custom_statuses table is empty
• [d49c50] fix: gate doctor tests on container port, not env var (GH-3087)
• [4bdf39] fix: handle JSON array format in SyncCustomTypesTable
• [63770b] fix: handle read-only Go module cache files in test temp dir cleanup
• [b59983] fix: handle release archives that extract into a subdirectory (#3167)
• [15f8a1] fix: harden bootstrap database naming and reject empty db param (GH#3029)
• [05a906] fix: include comment bodies in bd export JSONL output
• [ad285a] fix: include comment bodies in export and fix same-second dedup on import (#3009)
• [a3923e] fix: narrow cross-version smoke CI triggers and warn on high skip rate
• [23bfd0] fix: parse create output for versions without --silent flag
• [8d94fa] fix: preserve dependencies and labels in SQLite-era JSONL migration (#3079) (#3082)
• [f0adda] fix: prevent silent fallback to embedded mode when shared-server is active (GH#2949)
• [f70079] fix: proper failure reporting for cross-version smoke test
• [98d8e7] fix: queue concurrent embedded Dolt callers instead of failing (#3005)
• [7916e0] fix: remove ICU runtime dependency from release binaries (#3066)
• [8ccb82] fix: remove duplicate testutil import in validation_test.go
• [9d0b7a] fix: remove nonexistent -i flag from bd import references (#3200)
• [70e159] fix: remove redundant os.Stat check after FindBeadsDir
• [6686e1] fix: remove set -e to prevent dolt server crashes killing the script
• [c91105] fix: remove stale worktree guard in rename-prefix
• [164e25] fix: remove unsupported stepping-stone migration paths (#3073) (#3110)
• [5d9e87] fix: replace CWD-only check with walk-up in FindBeadsDir (GH#3027)
• [d588fb] fix: replace blanket .claude/ gitignore with specific ignores (GH#3182) (#3190)
• [f443df] fix: resolve CI failures from flock, version bump, and lint (#2981)
• [9ed189] fix: resolve go install failure on Windows due to ICU header dependency (#3013) (#3112)
• [a6a28d] fix: resolve backup_export conflict in bd backup init/remove (#2962) (#2980)
• [234da6] fix: resolve remaining 11 CI test failures (#2983)
• [97fea9] fix: respect dolt.auto-start=false, prevent rogue server spawns (#3058)
• [7e7104] fix: restore general-purpose CLAUDE.md, relocate Emma rig notes (GH-3078) (#3169)
• [652d32] fix: set FS_NOCOW_FL on .beads/ at init to avoid btrfs kworker thrashing (#3162)
• [64678b] fix: show diverged-history guidance on auto-push failure (#3138)
• [935a20] fix: silence dolt sql-server NewConnection log spam (#3160)
• [903583] fix: smoke test mutations + add PR gate trigger (GH-2968)
• [b8ec14] fix: surface auto-export and auto-backup errors to stderr (#3122)
• [053736] fix: unblock SQLite-era migration by clearing old DB before init (#3070) (#3077)
• [4fc045] fix: unblock v0.62.0 migration test by allowing Dolt auto-start (#3072) (#3076)
• [1cbde7] fix: update steveyegge references in claude-plugin layer (#3060)
• [9b3afb] fix: use American English spelling for misspell linter
• [145f1a] fix: use CGO_ENABLED=0 for pre-commit linter
• [c2c230] fix: use FindBeadsDir for worktree-aware reset
• [65f752] fix: use bd daemon/dolt stop for reliable server cleanup
• [b93cb4] fix: use default database name when metadata.json is missing (#2988) (#2989)
• [0f6c30] fix: use main repo root for hooks path in worktrees
• [7226e2] fix: use type "molecule" for formula root beads instead of "epic"
• [33109b] fix: use worktree fallback in bootstrap path synthesis
• [355cc9] fix: use worktree-aware beads dir in doctor checks
• [feb2d5] fix: worktree-aware fingerprint prevents repo ID mismatch (GH-2867) (#3123)
• [785253] fix: worktree-aware path resolution in config validate and preflight
• [1ba4ff] fix: write metadata.json in ensureBeadsDirForPath + contributor tests (#2988) (#2996)

Others

• [3cf374] +# Beads / Dolt files (added by bd init) +.beads-credential-key
• [eaa6a8] /.goreleaser.yml: make windows use embedded and cgo (#2990)
• [bf028b] /cmd/bd/context_cmd.go: keep deprecated field
• [638550] /cmd/bd/dolt.go: fix remote overwrite
• [1444c6] /cmd/bd/shared_server_integration_test.go: log times in verbose mode
• [977876] /cmd/bd/shared_server_integration_test.go: run behind env var
• [5b81cb] /cmd/bd: some cleanup
• [c96008] /cmd/bd: unify behavior of bd init and bootstrap
• [b483fb] /internal/storage/dolt: optimize schema migrations
• [457df7] /internal/storage/embeddeddolt: make backfill schema robust
• [f6ef51] /internal/storage/issueops/ready_work.go: fix time
• [3aef85] /internal/storage/schema/schema.go: fix test
• [9aa9b8] /internal/storage/schema/schema.go: fix tests
• [40e5eb] /internal/storage/schema: use shared schema package
• [f74f9f] /internal/storage/{dolt,embeddeddolt}: update embedded schema to match dolt server
• [65dbdb] /internal/storage: fix migration issue
• [ab9c2f] /internal/storage: pr feedback
• [f07978] /internal/storage: remove conflicting column on schema migration table
• [b4284a] /internal/storage: shared ensure ignored
• [cbfdc6] /internal/testutil/testdoltcommon.go: use latest dolt
• [168413] /{cmd,docs,internal}: get bootstrap and init working correctly and remote agnostic
• [fef1d1] /{cmd,internal,scripts}: use dsn helpers
• [4b3b06] /{cmd,internal}: fix lint
• [50f715] /{cmd,internal}: move local only state to dolt ignored tables
• [c71930] /{cmd,internal}: pr feedback
• [0c2dfc] /{cmd,internal}: shared server concurrency tests
• [a08497] /{cmd,internal}: some cleanup
• [7ada13] Add az:// (Azure Blob Storage) as a recognized Dolt remote URL scheme (#3101)
• [9730a8] Add documentation link and deepwiki reference. (#2978)
• [8e9120] Add release stability gate for upgrade safety (GH#2951) (#2963)
• [8c8329] Add side-effect hints for config set/unset commands (#3089)
• [f09970] Allow BEADS_DOLT_READY_TIMEOUT to override waitForReady timeout (#3188)
• [fda23d] Default test/install helpers to gms_pure_go (#3259)
• [69a13b] Fix GetCustomTypes swallowing DB errors, breaking bd update --type for custom types (#3159)
• [2568b6] Fix bd list watch hierarchy consistency (#3236)
• [ed78d0] Fix doctor hangs in non-interactive and artifact scans (GH-3092) (#3109)
• [9b4896] Fix formula search paths for worktree-aware beads dirs (#3235)
• [27b7ac] Fix init leaving beads.role unset in edge cases (GH#2950) (#2964)
• [b6e556] Fix jira.priority_map.* config not read on push/pull (#3130)
• [03bb3e] Fix shared-server init mode selection
• [ef6c6e] Follow up remaining runtime .beads fallbacks after GH#3124 (#3183)
• [e42f49] Improve config list: dynamic yaml key discovery and comprehensive env var detection (#3088)
• [8ec8f7] Update nix install for v1.0.0 (#3064)
• [4fe05a] Use getting started docs as bugs to fix (#3034)
• [1b9b26] Warn on shared-server embedded metadata mismatch
• [21910a] [codex] Fix installer ICU/CGO fallback handling (#2965)
• [c99cf4] add bd init fallback when candidate suggests it
• [48f611] add cross-version smoke test for upgrade compatibility (GH#2968)
• [149938] add migration fallback and prefix with special chars
• [5eca89] add pull_request trigger to cross-version smoke test workflow
• [c9cefe] add tag trigger to cross-version smoke test workflow
• [dfd1ad] chore(bootstrap): remove unreachable nil-cfg guard in finalizeSyncedBootstrap (#3222)
• [69eefd] chore(deps): bump fastmcp from 3.2.0 to 3.2.3 in /integrations/beads-mcp (#3173)
• [5530a1] chore(deps): bump github.com/anthropics/anthropic-sdk-go (#3178)
• [1fd569] chore(deps): bump github.com/testcontainers/testcontainers-go (#3176)
• [76229e] chore(deps): bump github.com/testcontainers/testcontainers-go/modules/dolt (#3177)
• [c64047] chore(deps): bump go.opentelemetry.io/otel from 1.42.0 to 1.43.0 (#3002)
• [7cd981] chore(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp (#3174)
• [88e77e] chore(deps): bump go.opentelemetry.io/otel/exporters/stdout/stdouttrace (#3003)
• [41f6b2] chore(deps): bump go.opentelemetry.io/otel/sdk from 1.42.0 to 1.43.0 (#3004)
• [055eef] chore(deps): bump golang.org/x/sys from 0.42.0 to 0.43.0 (#3175)
• [6f15e7] ci: add merge_group support and cancel stale runs (#3069)
• [7fb509] clarify --issues + --parent flag interaction in selective sync (#3056)
• [e7a554] fix ci: test: align auto-start precedence expectation (#3063)
• [a61911] merge: resolve conflicts with main for PR [#3146]
• [1a05da] refactor(dolt): make connection pool lifetime configurable with longer default (#3163)
• [231c88] refactor: deduplicate migration logic into runMigrations helper
• [296008] refactor: improve custom status error message per review feedback
• [138a2b] refactor: remove redirect file creation from bd worktree create (#3051)
• [0d1185] refactor: simplify worktree root resolution in hooks
• [4c52b9] release: beads v1.0.1
• [5e6e5e] remove migration fallback — candidate doesn't suggest it to users
• [7ea14b] security: harden remote URL validation at config parse time (#3210)
• [2ed8cb] test(audit): prove concurrent-writer ID uniqueness invariant (#3164)