website/docs/getting-started/installation.md
Complete installation guide for all platforms.
brew install beads
Why Homebrew?
brew upgradecurl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
The installer will:
go install if Go is availableIf you install via go install or build from source, you need system dependencies for CGO:
macOS (Homebrew):
brew install icu4c zstd
Linux (Debian/Ubuntu):
sudo apt-get install -y libicu-dev libzstd-dev
Linux (Fedora/RHEL):
sudo dnf install -y libicu-devel libzstd-devel
If you see unicode/uregex.h missing on macOS, icu4c is keg-only. Use:
ICU_PREFIX="$(brew --prefix icu4c)"
CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest
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/gastownhall/beads
cd beads
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/
Via Homebrew (works on Linux too):
brew install beads
Arch Linux (AUR):
# Install from AUR
yay -S beads-git
# or
paru -S beads-git
Via go install:
go install github.com/steveyegge/beads/cmd/bd@latest
Via quick install script:
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
Via go install:
go install github.com/steveyegge/beads/cmd/bd@latest
Beads ships with native Windows support—no MSYS or MinGW required.
Prerequisites:
%USERPROFILE%\go\bin to your PATH)Via PowerShell script:
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
The script installs a prebuilt Windows release if available. Go is only required for go install or building from source.
Via go install:
go install github.com/steveyegge/beads/cmd/bd@latest
If you see unicode/uregex.h missing while building, use the PowerShell install script instead.
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
How it works:
bd prime automatically on session startbd prime provides ~1-2k tokens of workflow contextbd CLI commands directlybd init) auto-sync the databaseWhy this is recommended:
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"
}
}
}
After installing, verify bd is working:
bd version
bd help
bd: command not foundbd 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"
zsh: killed bd or crashes on macOSThis is typically caused by CGO/SQLite compatibility issues:
# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
brew upgrade beads
go install github.com/steveyegge/beads/cmd/bd@latest
For post-upgrade steps (hooks, migrations), see Upgrading.
After installation:
cd your-project && bd init