Installing bd

Complete installation guide for all platforms.

Components Overview

Beads has several components - here's what they are and when you need them:

How they relate:

• The bd CLI is the core - install it first via Homebrew, npm, or script
• The Plugin enhances Claude Code with slash commands but requires the CLI installed
• The MCP server is an alternative to the CLI for environments without shell access

Important: Beads is installed system-wide, not cloned into your project. The .beads/ directory in your project only contains the issue database.

Typical setups:

Are they mutually exclusive? No - you can have CLI + Plugin + MCP all installed. They don't conflict. But most users only need the CLI.

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

Mise-en-place (macOS/Linux/Windows)

You can install beads using mise in 2 different ways:

1. Install the latest github release

mise install github:gastownhall/beads
mise use -g github:gastownhall/beads

2. Build the latest code from git using go:

mise install go:github.com/steveyegge/beads/cmd/bd@latest
mise use -g go:github.com/steveyegge/beads/cmd/bd

NOTE: The -g enables beads globally. To enable project-specific versions, omit that.

Why Mise?

• ✅ Same as Homebrew: simple, updates via mise up, works without Go, handles PATH
• ✅ Supports all platforms
• ✅ Always the latest release
• ✅ May optionally use a different version for specific projects

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)
• Verify downloaded release archives against release checksums.txt
• Install via go install if Go is available
• Fall back to building from source if needed
• Guide you through PATH setup if necessary

On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in:

BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

Comparison of Installation Methods

TL;DR: Use Homebrew if available. Use npm if you're in a Node.js environment. Use the script for quick one-off installs or CI.

A note on go install capability

go install supports two build modes that give different capabilities:

• Nocgo (simplest, default in this doc): CGO_ENABLED=0 go install .... Works on any machine with a Go toolchain, no C compiler needed. Produces a server-mode-only binary — you must run an external dolt sql-server and use bd init --server. See DOLT.md for server-mode setup.
• Cgo (embedded-capable): CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install .... Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend — bd init Just Works.

If you don't have a preference, brew install beads / install.sh give you the embedded-capable build with no fuss.

Platform-Specific Installation

macOS

Via Homebrew (recommended):

brew install beads

Via go install (server-mode only, simplest):

CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server   (requires a running dolt sql-server)

Via go install (embedded-capable, needs Xcode CLI tools):

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   # uses gms_pure_go tag and CGO
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

Thanks to @v4rgas for maintaining the AUR package!

Via go install (server-mode only, simplest):

CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server   (requires a running dolt sql-server)

Via go install (embedded-capable, needs gcc):

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   # uses gms_pure_go tag and CGO
sudo mv bd /usr/local/bin/

FreeBSD

Via Quick Install Script:

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

Via go install (server-mode only, simplest):

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

Windows 11

Beads now 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 and verifies the downloaded ZIP checksum against release checksums.txt. Go is only required for go install or building from source.

Via go install (server-mode only, simplest):

$env:CGO_ENABLED=0
go install github.com/steveyegge/beads/cmd/bd@latest
# Then: bd init --server   (requires a running dolt sql-server)

This produces a server-mode-only binary with no C compiler requirement — the fastest path to a working bd on Windows.

Via go install (embedded-capable, needs MinGW):

$env:CGO_ENABLED=1
$env:GOFLAGS="-tags=gms_pure_go"
go install github.com/steveyegge/beads/cmd/bd@latest

Requires MinGW-w64 gcc on your PATH. ICU is not required — gms_pure_go selects Go's stdlib regexp.

From source:

git clone https://github.com/gastownhall/beads
cd beads
make build   # uses gms_pure_go tag and CGO
Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\

The -tags gms_pure_go flag tells go-mysql-server to use Go's stdlib regexp instead of ICU.

Verify installation:

bd version

Windows notes:

• The Dolt server listens on a loopback TCP endpoint
• Allow bd.exe loopback traffic through any host firewall

Build Dependencies (Contributors Only)

Note: These dependencies are only needed if you build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely.

Building from source requires a C compiler (for CGO / embedded Dolt). ICU is not required -- all builds use the gms_pure_go tag which selects Go's stdlib regexp instead of ICU regex. See ICU-POLICY.md for details.

macOS (Homebrew):

brew install zstd

Linux (Debian/Ubuntu):

sudo apt-get install -y libzstd-dev

Linux (Fedora/RHEL):

sudo dnf install -y libzstd-devel

For maintainers only: If you intentionally need to run scripts/test-icu-path.sh (which exercises the leftover ICU code path), install ICU headers: brew install icu4c (macOS) or sudo apt-get install -y libicu-dev (Linux). This is not needed for normal development.

IDE and Editor Integrations

CLI + Hooks (Recommended for Claude Code)

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 mux      # Mux - creates/updates AGENTS.md

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
• More sustainable - Less compute per request

Verify installation:

bd setup claude --check   # Check Claude Code integration
bd setup cursor --check   # Check Cursor integration
bd setup aider --check    # Check Aider integration
bd setup codex --check    # Check Codex integration
bd setup mux --check      # Check Mux integration

Claude Code Plugin (Optional)

For enhanced UX with slash commands:

# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
# Restart Claude Code

The plugin adds:

• Slash commands: /beads:ready, /beads:create, /beads:show, /beads:update, /beads:close, etc.
• Task agent for autonomous execution

See PLUGIN.md for complete plugin documentation.

GitHub Copilot (VS Code)

For VS Code with GitHub Copilot:

1. Install beads-mcp:

   bashCopy

   uv tool install beads-mcp
   

2. Configure MCP - Create .vscode/mcp.json in your project:

   jsonCopy

   {
     "servers": {
       "beads": {
         "command": "beads-mcp"
       }
     }
   }
   

   For all projects: Add to VS Code user-level MCP config:

   Platform	Path
   macOS	~/Library/Application Support/Code/User/mcp.json
   Linux	~/.config/Code/User/mcp.json
   Windows	%APPDATA%\Code\User\mcp.json

   jsonCopy

   {
     "servers": {
       "beads": {
         "command": "beads-mcp",
         "args": []
       }
     }
   }
   

3. Initialize project:

   bashCopy

   bd init --quiet
   

4. Reload VS Code

See COPILOT_INTEGRATION.md for complete setup guide.

MCP Server (Alternative - for MCP-only environments)

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

Configuration for Sourcegraph Amp:

Add to your MCP settings:

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Trade-offs:

• ✅ Works in MCP-only environments
• ❌ Higher context overhead (MCP schemas add 10-50k tokens)
• ❌ Additional latency from MCP protocol

See integrations/beads-mcp/README.md for detailed MCP server documentation.

Verifying Installation

After installing, verify bd is working:

bd version
bd help

Troubleshooting Installation

For additional troubleshooting, see TROUBLESHOOTING.md.

bd: command not found

bd is not in your PATH. Either:

# 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 (server-mode only, no C compiler needed)
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

zsh: killed bd or crashes on macOS

Some users report crashes when running bd init or other commands on macOS. This is typically caused by CGO/SQLite compatibility issues.

Workaround:

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

# Or if building from source
git clone https://github.com/gastownhall/beads
cd beads
CGO_ENABLED=1 go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/

If you installed via Homebrew, this shouldn't be necessary as the formula already enables CGO. If you're still seeing crashes with the Homebrew version, please file an issue.

Claude Code Plugin: MCP server fails to start

If the Claude Code plugin's MCP server fails immediately after installation, it's likely that uv is not installed or not in your PATH.

Symptoms:

• Plugin slash commands work, but MCP tools are unavailable
• Error logs show command not found: uv
• Server fails silently on startup

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart your shell or update PATH
source ~/.local/bin/env

# Verify uv is available
which uv

# Restart Claude Code

See the "Claude Code Plugin" section above for alternative installation methods (Homebrew, pip).

Next Steps

After installation:

1. Initialize a project: cd your-project && bd init
2. Configure your agent: Add bd instructions to AGENTS.md (see README.md)
3. Learn the basics: See QUICKSTART.md for a tutorial
4. Explore examples: Check out the examples/ directory

Updating bd

Use the update command that matches how you installed 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

npm

npm update -g @beads/bd

bun

bun install -g --trust @beads/bd

go install

Use whichever mode you installed with originally:

# 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

From source

cd beads
git pull
go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/

After Upgrading (Recommended)

bd info --whats-new
bd hooks install
bd version

Uninstalling

To completely remove Beads from a repository, see UNINSTALLING.md.