The repository has moved to gastownhall/beads, but released Go modules still declare github.com/steveyegge/beads. The installer fallback should use the declared module path, and the docs/check should keep future guidance from regressing. _codex-gpt-5.5-medium on behalf of matt wilkie_
18 KiB
Installing bd
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
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
NOTE: The -g enables beads globally. To enable project-specific versions, omit that.
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 (All Platforms)
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 |
| 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.
A note on go install capability
go install supports two build modes that give different capabilities:
- Nocgo (simplest, default in this doc):
CGO_ENABLED=0 go install .... 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.md for server-mode setup. - Cgo (embedded-capable):
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install .... Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend —bd initJust Works.
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 / install.sh give you the embedded-capable build with no fuss.
Platform-Specific Installation
macOS
Via Homebrew (recommended):
brew install beads
Via go install (server-mode only, simplest):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server (requires a running dolt sql-server)
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 # uses gms_pure_go tag and CGO
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, simplest):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server (requires a running dolt sql-server)
Via go install (embedded-capable, needs gcc):
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 # uses gms_pure_go tag and CGO
sudo mv bd /usr/local/bin/
FreeBSD
Via Quick Install Script:
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Via go install (server-mode only, simplest):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Windows 11
Beads now 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, simplest):
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server (requires a running dolt sql-server)
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 MinGW):
$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest
Requires MinGW-w64 gcc on your PATH. ICU is not required — gms_pure_go selects Go's stdlib regexp.
From source:
git clone https://github.com/gastownhall/beads
cd beads
make build # uses gms_pure_go tag and CGO
Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\
The -tags gms_pure_go flag tells go-mysql-server to use Go's stdlib regexp instead of ICU.
Verify installation:
bd version
Windows notes:
- The Dolt server listens on a loopback TCP endpoint
- Allow
bd.exeloopback traffic through any host firewall
Build Dependencies (Contributors Only)
Note: 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) orsudo apt-get install -y libicu-dev(Linux). This is not needed for normal development.
IDE and Editor Integrations
CLI + Hooks (Recommended for Claude Code)
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/PreCompact 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
- More sustainable - Less compute per request
Verify installation:
bd setup claude --check # Check Claude Code integration
bd setup copilot --check # Check GitHub Copilot CLI project integration
bd setup cursor --check # Check Cursor integration
bd setup aider --check # Check Aider integration
bd setup codex --check # Check Codex integration
bd setup factory --check # Check Factory.ai integration
bd setup mux --check # Check Mux integration
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 PLUGIN.md for complete plugin documentation.
GitHub Copilot (VS Code)
For VS Code with GitHub Copilot:
-
Install beads-mcp:
uv tool install beads-mcp -
Configure MCP - Create
.vscode/mcp.jsonin your project:{ "servers": { "beads": { "command": "beads-mcp" } } }For all projects: Add to VS Code user-level MCP config:
Platform Path macOS ~/Library/Application Support/Code/User/mcp.jsonLinux ~/.config/Code/User/mcp.jsonWindows %APPDATA%\Code\User\mcp.json{ "servers": { "beads": { "command": "beads-mcp", "args": [] } } } -
Initialize project:
bd init --quiet -
Reload VS Code
See COPILOT_INTEGRATION.md for complete setup guide.
GitHub Copilot CLI
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.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_INTEGRATION.md for the full guide.
MCP Server (Alternative - for MCP-only environments)
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"
}
}
}
Configuration for Sourcegraph Amp:
Add to your MCP settings:
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
Trade-offs:
- ✅ Works in MCP-only environments
- ❌ Higher context overhead (MCP schemas add 10-50k tokens)
- ❌ Additional latency from MCP protocol
See integrations/beads-mcp/README.md for detailed MCP server documentation.
Verifying Installation
After installing, verify bd is working:
bd version
bd help
Troubleshooting Installation
For additional troubleshooting, see TROUBLESHOOTING.md.
bd: command not found
bd is not in your PATH. Either:
# 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 (server-mode only, no C compiler needed)
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
zsh: killed bd or crashes on macOS
Some users report crashes when running bd init or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues.
Workaround:
# Install an embedded-capable build
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
# Or if building from source
git clone https://github.com/gastownhall/beads
cd beads
CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
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.
Claude Code Plugin: MCP server fails to start
If the Claude Code plugin's MCP server fails immediately after installation, it's likely that uv is 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 the "Claude Code Plugin" section above for alternative installation methods (Homebrew, pip).
Next Steps
After installation:
- Initialize a project:
cd your-project && bd init - Configure your agent:
bd initcreates/updatesAGENTS.mdand installs project Claude/Codex integrations by default; runbd setup --listfor richer integrations orbd onboardfor a manual fallback snippet - Learn the basics: See QUICKSTART.md for a tutorial
- Explore examples: Check out the examples/ directory
Updating bd
Use the update command that matches how you installed bd.
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/
After Upgrading (Recommended)
bd info --whats-new
bd hooks install
bd version
Uninstalling
To completely remove Beads from a repository, see UNINSTALLING.md.