Installing bd

Complete installation guide for all platforms.

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

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

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 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 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 by default unless you use --skip-agents or --stealth
• 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
• bd onboard prints the small manual snippet for unsupported agents or custom instruction files

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, or run bd setup --list