Skip to main content
Version: Next

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​

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 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 by default unless you use --skip-agents or --stealth
  • Editor hooks/rules inject bd prime automatically on session start
  • Codex 0.129.0+ uses native /hooks for startup and compaction-aware context refresh
  • bd prime provides ~1-2k tokens of workflow context
  • You use bd CLI commands directly
  • Git hooks (installed by bd init) refresh exports and legacy fallbacks; bd dolt push/pull syncs 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