Installing bd

Complete installation guide for all platforms.

Components Overview

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

Component	What It Is	When You Need It
bd CLI	Core command-line tool	Always - this is the foundation
Claude Code Plugin	Slash commands + enhanced UX	Optional - if you want `/beads:ready`, `/beads:create` commands
MCP Server (beads-mcp)	Model Context Protocol interface	Only for MCP-only environments (Claude Desktop, Amp)

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:

Environment	What to Install
Claude Code, Cursor, Windsurf	bd CLI (+ optional Plugin for Claude Code)
GitHub Copilot (VS Code)	bd CLI + MCP server
Claude Desktop (no shell)	MCP server only
Terminal / scripts	bd CLI only
CI/CD pipelines	bd CLI only

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:

Install the latest github release

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

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

Comparison of Installation Methods

Method	Best For	Updates	Prerequisites	Notes
Homebrew	macOS/Linux users	`brew upgrade beads`	Homebrew	Recommended. Handles everything automatically
npm	JS/Node.js projects	`npm update -g @beads/bd`	Node.js	Convenient if npm is your ecosystem
bun	JS/Bun.js projects	`bun install -g --trust @beads/bd`	Bun.js	Convenient if bun is your ecosystem
Install script	Quick setup, CI/CD	Re-run script	curl, bash	Good for automation and one-liners
go install	Contributors / Go developers	Re-run command	Go 1.24+	Builds from source, always latest
From source	Contributors only	`git pull && go build`	Go, git	Full control, can modify code
AUR (Arch)	Arch Linux users	`yay -Syu`	yay/paru	Community-maintained

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.

Platform-Specific Installation

macOS

Via Homebrew (recommended):

brew install beads

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

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/

FreeBSD

Via Quick Install Script:

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

Via go install:

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/steveyegge/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.

Dolt backend on Windows: Supported via pure-Go regex backend. Windows builds automatically use Go's stdlib regexp instead of ICU regex to avoid CGO/header dependencies. If you need full ICU regex semantics, use Linux/macOS (or WSL) with ICU installed.

Via go install:

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

ICU is not required on Windows. The regex backend uses pure Go automatically.

From source:

git clone https://github.com/steveyegge/beads
cd beads
make build
# Or without Make:
go build -tags gms_pure_go -o bd.exe ./cmd/bd
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. Additionally, the vendored go-icu-regex library has a Windows-specific pure-Go implementation (regex_windows.go) that avoids ICU entirely. No C compiler or ICU libraries are needed.

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 install via go install or build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely.

If you install via go install or build from source, you need system dependencies for CGO:

macOS (Homebrew):

brew install icu4c zstd

Linux (Debian/Ubuntu):

sudo apt-get install -y libicu-dev libzstd-dev

Linux (Fedora/RHEL):

sudo dnf install -y libicu-devel libzstd-devel

If you see unicode/uregex.h missing on macOS, icu4c is keg-only. Use:

ICU_PREFIX="$(brew --prefix icu4c)"
CGO_CFLAGS="-I${ICU_PREFIX}/include" CGO_CPPFLAGS="-I${ICU_PREFIX}/include" CGO_LDFLAGS="-L${ICU_PREFIX}/lib" go install github.com/steveyegge/beads/cmd/bd@latest

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 steveyegge/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:

Install beads-mcp:
```
uv tool install beads-mcp
```
Configure MCP - Create .vscode/mcp.json in your project:
```
{
  "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
```
{
  "servers": {
    "beads": {
      "command": "beads-mcp",
      "args": []
    }
  }
}
```
Initialize project:
```
bd init --quiet
```
Reload VS Code

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

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
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/steveyegge/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:

Initialize a project: cd your-project && bd init
Configure your agent: Add bd instructions to AGENTS.md (see README.md)
Learn the basics: See QUICKSTART.md for a tutorial
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/steveyegge/beads/main/scripts/install.sh | bash

PowerShell Installer (Windows)

irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex

Homebrew

brew upgrade beads

npm

npm update -g @beads/bd

bun

bun install -g --trust @beads/bd

go install

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installing bd

Components Overview

Quick Install (Recommended)

Homebrew (macOS/Linux)

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

Quick Install Script (All Platforms)

Comparison of Installation Methods

Platform-Specific Installation

macOS

Linux

FreeBSD

Windows 11

Build Dependencies (Contributors Only)

IDE and Editor Integrations

CLI + Hooks (Recommended for Claude Code)

Claude Code Plugin (Optional)

GitHub Copilot (VS Code)

MCP Server (Alternative - for MCP-only environments)

Verifying Installation

Troubleshooting Installation

`bd: command not found`

`zsh: killed bd` or crashes on macOS

Claude Code Plugin: MCP server fails to start

Next Steps

Updating bd

Quick Install Script (macOS/Linux/FreeBSD)

PowerShell Installer (Windows)

Homebrew

npm

bun

go install

From source

After Upgrading (Recommended)

Uninstalling

FilesExpand file tree

INSTALLING.md

Latest commit

History

INSTALLING.md

File metadata and controls

Installing bd

Components Overview

Quick Install (Recommended)

Homebrew (macOS/Linux)

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

Quick Install Script (All Platforms)

Comparison of Installation Methods

Platform-Specific Installation

macOS

Linux

FreeBSD

Windows 11

Build Dependencies (Contributors Only)

IDE and Editor Integrations

CLI + Hooks (Recommended for Claude Code)

Claude Code Plugin (Optional)

GitHub Copilot (VS Code)

MCP Server (Alternative - for MCP-only environments)

Verifying Installation

Troubleshooting Installation

bd: command not found

zsh: killed bd or crashes on macOS

Claude Code Plugin: MCP server fails to start

Next Steps

Updating bd

Quick Install Script (macOS/Linux/FreeBSD)

PowerShell Installer (Windows)

Homebrew

npm

bun

go install

From source

After Upgrading (Recommended)

Uninstalling

`bd: command not found`

`zsh: killed bd` or crashes on macOS