website/versioned_docs/version-1.1.2/getting-started/installation.md
Complete installation guide for all platforms.
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?
brew upgradecurl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
The installer will:
go install modes if Go is availableUse Homebrew, npm, or the install script if you do not specifically need go install.
go install has two supported modes:
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latestCGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latestICU 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.
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):
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/
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 (server-mode only):
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
Via go install (embedded-capable):
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go 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 (server-mode only):
CGO_ENABLED=0 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 (server-mode only):
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
Via go install (embedded-capable):
$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest
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 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 init creates or updates AGENTS.md and installs project Claude/Codex integrations by default unless you use --skip-agents or --stealthbd prime automatically on session start/hooks for startup and compaction-aware context refreshbd prime provides ~1-2k tokens of workflow contextbd CLI commands directlybd init) refresh exports and legacy fallbacks; bd dolt push/pull syncs the databasebd onboard prints the small manual snippet for unsupported agents or custom instruction filesWhy 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"
# 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 macOSThis 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
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
# 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
For post-upgrade steps (hooks, migrations), see Upgrading.
After installation:
cd your-project && bd initbd setup --list