beads/website/docs/getting-started/installation.md
matt wilkie e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
2026-04-25 11:30:19 -07:00

6.2 KiB

id title sidebar_position
installation Installation 1

Installing bd

Complete installation guide for all platforms.

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

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)
  • Fall back to the supported go install modes if Go is available
  • Fall back to building from source if needed
  • Guide you through PATH setup if necessary

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:

  • 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

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.

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):

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

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

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\bin to your PATH)
  • 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. 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

IDE and Editor Integrations

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:

  • Editor hooks/rules inject bd prime automatically on session start
  • bd prime provides ~1-2k tokens of workflow context
  • You use bd CLI 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

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"
    }
  }
}

Verifying Installation

After installing, verify bd is working:

bd version
bd help

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

Updating 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

go install

# 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.

Next Steps

After installation:

  1. Initialize a project: cd your-project && bd init
  2. Learn the basics: See Quick Start
  3. Configure your agent: See IDE Setup