* feat(schema): never migrate an existing database without explicit consent (bd-qhn8y) Beads 1.2 release remediation. 1.2.0/1.2.1 auto-applied migrations 54-65 at store open on ANY command, including reads; older binaries then refuse the migrated database. MigrateUp now refuses pending main-sequence migrations on an existing database before any write (dolt_ignore seeding included) unless the operator consented: bd migrate / bd migrate schema (preview flags withhold), bd migrate --force, or BD_ALLOW_MIGRATE=1 (BD_ALLOW_REMOTE_MIGRATE honored as an alias). Fresh init and at-latest databases are unaffected; the #4259 remote gate keeps all its protections. Also: freeze shipped migrations (hash-pin test, main 0001-0065 + ignored 0001-0024), retract v1.2.0/v1.2.1 in go.mod, agent-executable un-migrate runbook (docs/recovery/unmigrate-schema-v65.md), and the upgrade smoke + historical migration harnesses now model the consent contract and assert the refusal carries guidance. No version bump here by design: cutting the release stays with the release owner. Rebased onto main800d43eb8d: the go.mod retract hunk is dropped - main already retracts v1.2.0/v1.2.1 (and v1.1.1) since #5782. The uow consent grant moves into the TestMain main added in #6441 (a second TestMain no longer compiles), and the new files are listed in the BUILD.bazel targets main now carries (gazelle). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(schema): cloned-workspace bootstrap carries creation-consent (bd-qhn8y) The consent gate treated a workspace `bd init --remote` / `bd bootstrap` just cloned into existence like a pre-existing database, refusing the smart gate's provably-safe first-mover migration and stranding init in the generic open-error path (bypassing the bd-4mpy7 finalize+guidance ergonomics). Cloning IS creating: those paths now record consent explicitly, and the #4259 remote-migrate gate still applies to them unchanged (consent is not its designated-migrator override). Fixes CI TestEmbeddedInit/remote_behind_schema_gate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(migration): consent first in main's wisp lanes too (bd-qhn8y) The rebase onto800d43eb8dbrought in #6049's wisp-plane lanes, which postdate this PR's harness changes. Each one makes an ordinary candidate command the first touch on an old-schema database, and the consent gate refuses it: - historical-dolt-upgrade-test.sh run_wisp_plane_upgrade opens with `bd list` before any migrate: "candidate could not open the seeded wisp workspace" for v1.0.1, v1.1.0, v1.1.2 and v1.2.2 (the Migration Test Harness dolt-runtime shard). - run_dirty_tracked_wisp_scenario (v1.1.2): the consent refusal stops the open before MigrateUp reaches the #5816 dirty tables, so the lane fails "without naming them". - upgrade-smoke-test.sh "Wisp plane survives upgrade" upgrades with a bare cand_init, so list/ready/blocked/update all hit the refusal (4 failures each for v1.3.0 and v1.3.1, both in the PR smoke set). Use the PR's own pattern: the explicit `bd migrate schema` is the first candidate touch (cand_upgrade in the smoke script). Base800d43eb8dpasses these lanes unchanged; with this fixup the full 14-version historical corpus and all five PR smoke versions pass. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(schema): close consent-gate review findings (bd-qhn8y) Review fixes for the migration-consent gate (adopt-pr review, attempts 1 and 2). Majors: - #4566 deadlock rebuilt one check earlier: on a database that is both behind and dirty, the consent refusal fired before the dirty-table guard, whose remedy (`bd dolt commit`) opens without consent. The working-set-reconcile opens now tolerate MigrateConsentError: embedded (toleratesConsentRefusal, WSR intent only) and server mode (LenientOpen's warnLenientOpenRefusal) print WorkingSetWarning and commit at the current schema; strict, read-only and RemoteSync opens still refuse. Covered by an embedded test (a refused open writes nothing: dolt_status, dolt_ignore and schema_migrations unchanged) and a server-mode integration subtest. - Bare `bd migrate` consented: isMigrateConsentCommand now matches only the schema verb, so `bd migrate` (metadata reconcile, including --update-repo-id, --inspect and --dry-run) no longer consents to a one-way migration; `bd migrate schema` and --force do. TestLocalMigrateConsentScope pins the scope through the root pre-run. The dirty-table warnings name `bd migrate schema` accordingly. - Runnable JSON hint: the JSON refusal follows the #4259 AgentDirective convention, a non-runnable hint plus a migrate_consent object (versions, pending, severity, human_decision_required, options) whose commands are retargeted with --global for the shared global database. The text refusal prints the same --global hint under `bd --global`. - Freeze floor: the hash-pinned freeze now covers what v1.3.x shipped, main 0001-0066 and ignored 0001-0026; the CHANGELOG puts new migrations in 0070+ / 0028+. - Fresh-bootstrap heal: MigrateUpWithLock with heal authority takes the consent-free migrate path, so a retried bd init whose first pass left a non-zero cursor converges; other lock callers keep the gate. Minors: the uow team-server guards are repinned on `bd migrate schema`; the un-migrate runbook is linked from the recovery index and cross-linked with the 1.2.1 repair-forward doc; the CHANGELOG BREAKING entry matches the shipped contract; harness comment grammar. Docs: the user docs and README named bare `bd migrate` as the step that applies schema migrations; they now say `bd migrate schema`, which also exists in the pinned docs release (v1.2.2) and in v1.3.x. The `bd migrate schema` help no longer claims migrations run automatically on store open. The Go remedy that sends a remote-gate stop to bare `bd migrate` for its migrate-or-adopt options is unchanged (pinned by TestNoticeSharedMigrateRefusalPerDecision). Upgrade smoke (attempt 2): the consent-gate assertion is graded only when the old binary left a database. Releases before v1.0 have no `init --non-interactive`, so prev_init creates nothing there and the candidate's `bd list` fails with "no beads database found", which has no consent guidance. Main's Bazel smoke lane (#7331) runs the newest 30 releases, 20 of them pre-1.0, under the required ci-gate; all 20 went red on the merge. The 10 v1.x releases still take the refusal branch. Shard manifest (pre-approval CI): the new embedded test TestEmbeddedMigrateConsent_BehindAndDirtyWorkingSetReconcileRecovers is listed in the Bazel 15-shard block of embedded-storage-test-shards.txt (incremental --write; shard 15). Main's ci lane runs TestStorageEmbeddedShardManifestGeneratorNotStale in //scripts:scripts_test, which fails on any unlisted top-level embeddeddolt test. Not addressed (optional): env-only consent docs for embedders, the unparseable BD_ALLOW_REMOTE_MIGRATE alias hint, and the harness `|| true` on `cand migrate schema`. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com> Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
18 KiB
| title | description |
|---|---|
| Installation | Install the bd CLI, Claude Code plugin, and MCP server on macOS, Linux, Windows, and FreeBSD via Homebrew, npm, or go install |
Complete installation guide for all platforms.
Components Overview
Beads has several components - here's what they are and when you need them:
| Component | What It Is | When You Need It |
|---|---|---|
| bd CLI | Core command-line tool | Always - this is the foundation |
| Claude Code Plugin | Slash commands + enhanced UX | Optional - if you want /beads:ready, /beads:create commands |
| MCP Server (beads-mcp) | Model Context Protocol interface | Only for MCP-only environments (Claude Desktop, Amp) |
How they relate:
- The bd CLI is the core - install it first via Homebrew, npm, or script
- The Plugin enhances Claude Code with slash commands but requires the CLI installed
- The MCP server is an alternative to the CLI for environments without shell access
Important: Beads is installed system-wide, not cloned into your project. The .beads/ directory in your project only contains the issue database.
Typical setups:
| Environment | What to Install |
|---|---|
| Claude Code, Cursor, Windsurf | bd CLI (+ optional Plugin for Claude Code) |
| GitHub Copilot (VS Code) | bd CLI + MCP server |
| Claude Desktop (no shell) | MCP server only |
| Terminal / scripts | bd CLI only |
| CI/CD pipelines | bd CLI only |
Are they mutually exclusive? No - you can have CLI + Plugin + MCP all installed. They don't conflict. But most users only need the CLI.
Quick Install (Recommended)
Homebrew (macOS/Linux)
brew install beads
Homebrew core's beads formula is the supported Homebrew package. If you
previously installed the old tap formula as bd, see
Migrating from the old Homebrew tap to
switch to the core formula.
Why Homebrew?
- Simple one-command install
- Automatic updates via
brew upgrade - No need to install Go
- Handles PATH setup automatically
Mise-en-place (macOS/Linux/Windows)
You can install beads using mise from the latest GitHub release:
mise install github:gastownhall/beads
mise use -g github:gastownhall/beads
The -g enables beads globally. To enable project-specific versions, omit it.
Why Mise?
- Same as Homebrew: simple, updates via
mise up, works without Go, handles PATH - Supports all platforms
- Always the latest release
- May optionally use a different release version for specific projects
Mise's Go backend follows the same caveats as go install; prefer the release backend above.
Quick Install Script (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
The installer will:
- Detect your platform (macOS/Linux/FreeBSD, amd64/arm64)
- Verify downloaded release archives against release
checksums.txt - Fall back to the supported
go installmodes if Go is available - Fall back to building from source if needed
- Guide you through PATH setup if necessary
On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in:
BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Comparison of Installation Methods
| Method | Best For | Updates | Prerequisites | Notes |
|---|---|---|---|---|
| Homebrew | macOS/Linux users | brew upgrade beads |
Homebrew | Recommended. Handles everything automatically |
| Mise | All platforms | mise up |
mise | Installs the latest GitHub release |
| npm | JS/Node.js projects | npm update -g @beads/bd |
Node.js | Convenient if npm is your ecosystem |
| bun | JS/Bun.js projects | bun install -g --trust @beads/bd |
Bun.js | Convenient if bun is your ecosystem |
| Install script | Quick setup, CI/CD | Re-run script | curl, bash | Good for automation and one-liners |
| go install (nocgo) | Go developers, simplest install | Re-run command | Go 1.24+ | Server-mode only (no embedded Dolt) |
| go install (cgo) | Go developers wanting embedded mode | Re-run command | Go 1.24+, C compiler | Full embedded-Dolt support |
| From source | Contributors only | git pull && go build |
Go, git | Full control, can modify code |
| AUR (Arch) | Arch Linux users | yay -Syu |
yay/paru | Community-maintained |
TL;DR: Use Homebrew if available. Use npm if you're in a Node.js environment. Use the script for quick one-off installs or CI.
Go Install and Build Dependencies
Use Homebrew, npm, or the install script if you do not specifically need go install.
go install has two supported modes that give different capabilities:
- Server-mode only (nocgo, simplest):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest. Works on any machine with a Go toolchain, no C compiler needed. Produces a server-mode-only binary — you must run an externaldolt sql-serverand usebd init --server. See Dolt for server-mode setup. - Embedded-capable (cgo):
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest. Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend —bd initJust Works.
ICU headers are not required. The embedded-capable command uses gms_pure_go so go-mysql-server uses Go's stdlib regexp instead of ICU.
Use the github.com/steveyegge/beads path for go install. The repository now lives under gastownhall/beads, but released Go modules still declare github.com/steveyegge/beads for compatibility.
If you don't have a preference, brew install beads or the install script give you the embedded-capable build with no fuss.
Build Dependencies (Contributors Only)
These dependencies are only needed if you build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely.Building from source requires a C compiler (for CGO / embedded Dolt). ICU is
not required — all builds use the gms_pure_go tag which selects Go's
stdlib regexp instead of ICU regex. See
ICU-POLICY.md
for details.
macOS (Homebrew):
brew install zstd
Linux (Debian/Ubuntu):
sudo apt-get install -y libzstd-dev
Linux (Fedora/RHEL):
sudo dnf install -y libzstd-devel
For maintainers only: if you intentionally need to run
scripts/test-icu-path.sh
(which exercises the leftover ICU code path), install ICU headers:
brew install icu4c (macOS) or sudo apt-get install -y libicu-dev (Linux).
This is not needed for normal development.
Platform-Specific Installation
macOS
Via Homebrew (recommended):
brew install beads
Via go install (server-mode only):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Via go install (embedded-capable, needs Xcode CLI tools):
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
From source:
git clone https://github.com/gastownhall/beads
cd beads
make build
sudo mv bd /usr/local/bin/
Linux
Via Homebrew (works on Linux too):
brew install beads
Arch Linux (AUR):
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
Thanks to @v4rgas for maintaining the AUR package!
Via go install (server-mode only):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Via go install (embedded-capable, needs gcc):
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
FreeBSD
Via quick install script:
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Via go install (server-mode only):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Windows 11
Beads ships with native Windows support—no MSYS or MinGW required.
Prerequisites:
- Go 1.24+ installed (add
%USERPROFILE%\go\binto yourPATH) - Git for Windows
Via PowerShell script:
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
The script installs a prebuilt Windows release if available and verifies the downloaded ZIP checksum against release checksums.txt. Go is only required for go install or building from source.
Via go install (server-mode only):
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
This produces a server-mode-only binary with no C compiler requirement — the fastest path to a working bd on Windows.
Via go install (embedded-capable, needs a Windows CGO toolchain):
$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest
Requires a GCC-compatible Windows CGO compiler on your PATH, such as
MinGW-w64/MSYS2 gcc or MSYS2 LLVM clang targeting windows-gnu
(clang64/clangarm64). ICU is not required — gms_pure_go selects
Go's stdlib regexp. Visual Studio cl.exe by itself is not enough because
Go passes GCC-style CGO flags; use a MinGW/MSYS2 toolchain, set CC, or set
WINDOWS_CGO_BINS when building from source.
From source:
git clone https://github.com/gastownhall/beads
cd beads
make build
Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\
Windows notes:
- The Dolt server listens on a loopback TCP endpoint
- Allow
bd.exeloopback traffic through any host firewall - Installed from npm,
bdis abd.cmdshim — Node'sexecFile/spawnneedshell: trueto run it (details)
IDE and Editor Integrations
CLI + Hooks (Recommended)
The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:
# 1. Install bd CLI (see Quick Install above)
brew install beads
# 2. Initialize in your project
cd your-project
bd init --quiet
# 3. Setup editor integration (choose one)
bd setup claude # Claude Code - installs SessionStart hooks
bd setup copilot # GitHub Copilot CLI - creates .copilot-plugin/plugin.json + .github/copilot-instructions.md
bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider # Aider - creates .aider.conf.yml
bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks
bd setup factory # Factory.ai Droid - creates/updates AGENTS.md
bd setup mux # Mux - creates/updates AGENTS.md
How it works:
bd initcreates or updatesAGENTS.mdand installs project Claude/Codex integrations by default unless you use--skip-agentsor--stealth- Editor hooks/rules inject
bd primeautomatically on session start - Codex 0.129.0+ uses native
/hooks: SessionStart injectsbd prime, compact hooks mark context stale, and the next prompt after compaction refreshes Beads context once bd primeprovides ~1-2k tokens of workflow context- You use
bdCLI commands directly - Git hooks (installed by
bd init) refresh exports and legacy fallbacks;bd dolt push/pullsyncs the database bd onboardprints the small manual snippet for unsupported agents or custom instruction files
Why this is recommended:
- Context efficient - ~1-2k tokens vs 10-50k for MCP tool schemas
- Lower latency - Direct CLI calls, no MCP protocol overhead
- Universal - Works with any editor that has shell access
Verify installation: every recipe supports a check flag, e.g. bd setup claude --check or bd setup copilot --check.
Claude Code Plugin (Optional)
For enhanced UX with slash commands:
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
# Restart Claude Code
The plugin adds:
- Slash commands:
/beads:ready,/beads:create,/beads:show,/beads:update,/beads:close, etc. - Task agent for autonomous execution
See Claude Code Plugin for complete plugin documentation.
GitHub Copilot
For VS Code with GitHub Copilot, install the MCP server (uv tool install beads-mcp) and create .vscode/mcp.json in your project — or add it to the VS Code user-level MCP config to enable it for all projects. See GitHub Copilot for the complete setup guide, including the user-level config paths per platform.
For the GitHub Copilot CLI terminal integration:
bd setup copilot # Install project Copilot plugin + repository instructions
bd setup copilot --check # Verify the project integration files exist
This setup is currently project-scoped only. It writes .copilot-plugin/plugin.json and .github/copilot-instructions.md; there is no separate --global or --project mode for Copilot today, and it does not manage ~/.copilot/... paths. See Copilot CLI for the full guide.
MCP Server (Alternative)
Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell):
# Using uv (recommended)
uv tool install beads-mcp
# Or using pip
pip install beads-mcp
Configuration for Claude Desktop (macOS):
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
For Sourcegraph Amp configuration and detailed MCP server documentation, see MCP Server.
Verifying Installation
After installing, verify bd is working:
bd version
bd help
Troubleshooting
For additional troubleshooting, see Troubleshooting.
bd: command not found
bd is not in your PATH:
# Check if installed
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall with the recommended installer
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
zsh: killed bd or crashes on macOS
This is typically caused by CGO/SQLite compatibility issues:
# Install an embedded-capable build
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please file an issue.
MCP server fails to start (standalone beads-mcp)
The Claude Code plugin itself does not bundle an MCP server. If you configured the standalone beads-mcp server (see MCP Server) and it fails immediately, uv is likely not installed or not in your PATH.
Symptoms:
- Plugin slash commands work, but MCP tools are unavailable
- Error logs show
command not found: uv - Server fails silently on startup
Solution:
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your shell or update PATH
source ~/.local/bin/env
# Verify uv is available
which uv
# Restart Claude Code
See Claude Code Plugin for alternative installation methods.
Updating bd
Upgrade checklist:
- With your current
bd, sync remote-backed databases before installing the new binary:bd dolt pushbd dolt pull - Back up before migration:
bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl - Upgrade using the command for your install method below.
- After upgrading:
bd info --whats-newbd hooks installbd version - If crossing a schema migration on a remote-backed database, only the
designated migrator runs:
bd migrate schemabd dolt push
Other clones should install the new binary and run bd bootstrap, not
independently migrate. For the full procedure, see Upgrading.
Quick install script (macOS/Linux/FreeBSD)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
PowerShell installer (Windows)
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
Homebrew
brew upgrade beads
npm
npm update -g @beads/bd
bun
bun install -g --trust @beads/bd
go install
Use whichever mode you installed with originally:
# Server-mode only
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Embedded-capable
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
From source
cd beads
git pull
make build
sudo mv bd /usr/local/bin/
Prereleases (e.g. release candidates) are published only as GitHub prereleases
and are not pushed to the stable Homebrew/npm/PyPI channels, so brew upgrade
and friends will not move you onto them — fetch the prerelease build explicitly.
For post-upgrade steps (hooks, migrations), see Upgrading.
Uninstalling
To completely remove Beads from a repository, see Uninstalling.
Next Steps
After installation:
- Initialize a project:
cd your-project && bd init - Learn the basics: See Quick Start
- Configure your agent: See IDE Setup, or run
bd setup --list - Explore examples: Check out the examples/ directory