Skip to main content

Installing bd

Complete installation guide for all platforms.

Homebrew (macOS/Linux)​

brew tap steveyegge/beads
brew install bd

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/steveyegge/beads/main/scripts/install.sh | bash

The installer will:

  • Detect your platform (macOS/Linux, amd64/arm64)
  • Install via go install if Go is available
  • Fall back to building from source if needed
  • Guide you through PATH setup if necessary

Platform-Specific Installation​

macOS​

Via Homebrew (recommended):

brew tap steveyegge/beads
brew install bd

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 tap steveyegge/beads
brew install bd

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

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/steveyegge/beads/main/install.ps1 | iex

Via go install:

go install github.com/steveyegge/beads/cmd/bd@latest

IDE and Editor Integrations​

CLI + Hooks (Recommended)​

The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:

# 1. Install bd CLI (see Quick Install above)
brew install bd

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

zsh: killed bd or crashes on macOS​

This is typically caused by CGO/SQLite compatibility issues:

# Build with CGO enabled
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest

Updating bd​

Homebrew​

brew upgrade bd

go install​

go install github.com/steveyegge/beads/cmd/bd@latest

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