Add docs/ICU-POLICY.md as the authoritative reference for how ICU is handled across all platforms. Update CONTRIBUTING.md and INSTALLING.md to stop listing ICU as a build requirement (it's test-only since all builds use gms_pure_go). Resolves confusion from overlapping PRs (#2991, #3066, #3112) where agents and contributors were doing/undoing each other's ICU fixes without a written policy. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
14 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 in 2 different ways:
- Install the latest github release
mise install github:steveyegge/beads
mise use -g github:steveyegge/beads
- Build the latest code from git using go:
mise install go:github.com/steveyegge/beads/cmd/bd@latest
mise use -g go:github.com/steveyegge/beads/cmd/bd
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 version for specific projects
Quick Install Script (All Platforms)
curl -fsSL https://raw.githubusercontent.com/steveyegge/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 - Install via
go installif 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/steveyegge/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 | Contributors / Go developers | Re-run command | Go 1.24+ | Builds from source, always latest |
| 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.
Platform-Specific Installation
macOS
Via Homebrew (recommended):
brew install beads
Via go install:
go install github.com/steveyegge/beads/cmd/bd@latest
From source:
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
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:
go install github.com/steveyegge/beads/cmd/bd@latest
From source:
git clone https://github.com/steveyegge/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
FreeBSD
Via Quick Install Script:
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
Via go install:
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/steveyegge/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.
Dolt backend on Windows: Supported via pure-Go regex backend. Windows builds automatically use Go's stdlib regexp instead of ICU regex to avoid CGO/header dependencies. If you need full ICU regex semantics, use Linux/macOS (or WSL) with ICU installed.
Via go install:
go install github.com/steveyegge/beads/cmd/bd@latest
ICU is not required on Windows. The regex backend uses pure Go automatically.
From source:
git clone https://github.com/steveyegge/beads
cd beads
make build
# Or without Make:
go build -tags gms_pure_go -o bd.exe ./cmd/bd
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.
Additionally, the vendored go-icu-regex library has a Windows-specific pure-Go implementation
(regex_windows.go) that avoids ICU entirely. No C compiler or ICU libraries are needed.
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 CI / test contributors only: If you need to run
scripts/test-cgo.sh(which exercises the 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 cursor # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider # Aider - creates .aider.conf.yml
bd setup codex # Codex CLI - creates/updates AGENTS.md
bd setup mux # Mux - creates/updates AGENTS.md
How it works:
- Editor hooks/rules inject
bd primeautomatically on session start bd primeprovides ~1-2k tokens of workflow context- You use
bdCLI commands directly - Git hooks (installed by
bd init) auto-sync the database
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 cursor --check # Check Cursor integration
bd setup aider --check # Check Aider integration
bd setup codex --check # Check Codex integration
bd setup mux --check # Check Mux integration
Claude Code Plugin (Optional)
For enhanced UX with slash commands:
# In Claude Code
/plugin marketplace add steveyegge/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.
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
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:
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
# Or if building from source
git clone https://github.com/steveyegge/beads
cd beads
CGO_ENABLED=1 go build -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: Add bd instructions to
AGENTS.md(see README.md) - 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/steveyegge/beads/main/scripts/install.sh | bash
PowerShell Installer (Windows)
irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
Homebrew
brew upgrade beads
npm
npm update -g @beads/bd
bun
bun install -g --trust @beads/bd
go install
go install github.com/steveyegge/beads/cmd/bd@latest
From source
cd beads
git pull
go build -o bd ./cmd/bd
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.