Installing Beads

Beads is available for macOS, Linux, Windows, and FreeBSD. Choose the installation method that works best for your environment.

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

Quick Install (Recommended)

macOS / Linux
Windows
FreeBSD

Shell Script

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

The installer will:

Detect your platform (macOS/Linux/FreeBSD, 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

Homebrew (Recommended)

brew install beads

Why Homebrew?

✅ Simple one-command install
✅ Automatic updates via brew upgrade
✅ No need to install Go
✅ Handles PATH setup automatically

PowerShell Script

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

Prerequisites:

Go 1.24+ installed
Git for Windows
Add %USERPROFILE%\go\bin to your PATH

The script installs a prebuilt Windows release if available. Go is only required for go install or building from source.

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.

Shell 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

Package Managers

Homebrew

brew install beads

Works on macOS and Linux.

npm

npm install -g @beads/bd

Convenient for JavaScript/Node.js projects.

Go

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

Requires Go 1.24+. Builds from source.

Arch Linux (AUR)

yay -S beads-git
# or
paru -S beads-git

Community-maintained by @v4rgas.

Alternative Package Managers

Mise-en-place

Mise works on all platforms and supports version management:

# Install latest GitHub release
mise install github:steveyegge/beads
mise use -g github:steveyegge/beads

# Or build from source with Go
mise install go:github.com/steveyegge/beads/cmd/bd@latest
mise use -g go:github.com/steveyegge/beads/cmd/bd

The -g flag enables Beads globally. Omit it for project-specific versions.

Bun

bun install -g --trust @beads/bd

Building from Source

Prerequisites

For go install or building from source, you need CGO dependencies:

macOS
Ubuntu / Debian
Fedora / RHEL
Windows

brew install icu4c zstd

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

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

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

sudo dnf install -y libicu-devel libzstd-devel

Build Steps

Clone the repository

git clone https://github.com/steveyegge/beads
cd beads

Build

go build -o bd ./cmd/bd
sudo mv bd /usr/local/bin/

On Windows, the -tags gms_pure_go flag enables pure Go regex (no ICU needed).

Verify installation

bd version
bd help

Installation Comparison

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 projects	`bun install -g --trust @beads/bd`	Bun	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	Go developers	Re-run command	Go 1.24+	Builds from source, always latest
From source	Contributors, custom builds	`git pull && go build`	Go, git	Full control, can modify code
AUR (Arch)	Arch Linux users	`yay -Syu`	yay/paru	Community-maintained
Mise	Version management	`mise up`	Mise	Supports project-specific versions

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.

Verify Installation

After installing, verify Beads is working:

bd version
bd help

Expected output:

$ bd version
bd version 0.20.5

$ bd help
bd - Distributed, git-backed issue tracker for AI agents

Usage:
  bd [command]

Available Commands:
  init        Initialize beads in current project
  create      Create a new issue
  list        List issues
  ready       Show ready work (no blockers)
  ...

IDE and Editor Integrations

After installing the CLI, set up your editor:

Claude Code / Cursor / Windsurf

Recommended approach for editors with shell access:

# 1. Install bd CLI (already done!)

# 2. Initialize in your project
cd your-project
bd init --quiet

# 3. Setup editor integration
bd setup claude   # Claude Code
bd setup cursor   # Cursor IDE
bd setup aider    # Aider
bd setup codex    # Codex CLI
bd setup mux      # Mux

How it works:

Editor hooks/rules inject bd prime on session start
bd prime provides ~1-2k tokens of workflow context
You use bd CLI commands directly
Git hooks (from bd init) auto-sync the database

Why this is recommended:

Context efficient - ~1-2k tokens vs 10-50k for MCP
Lower latency - Direct CLI calls, no protocol overhead
Universal - Works with any editor that has shell access

Verify installation:

bd setup claude --check
bd setup cursor --check

GitHub Copilot (VS Code)

For VS Code with GitHub Copilot, use the MCP server:

Install beads-mcp

uv tool install beads-mcp
# or
pip install beads-mcp

Configure MCP

Create .vscode/mcp.json in your project:

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

For all projects, add to 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`

Initialize project

bd init --quiet

Reload VS Code

Restart VS Code to load the MCP server.

MCP has higher context overhead (10-50k tokens for tool schemas) compared to direct CLI usage (~1-2k tokens).

Claude Desktop (MCP-only)

For environments without shell access:

Install beads-mcp

uv tool install beads-mcp

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

Troubleshooting

`bd: command not found`

Beads 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` (macOS crashes)

Some macOS users report crashes. This is typically a CGO/SQLite compatibility issue. Workaround:

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

# Or build 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, CGO is already enabled. If you’re still seeing crashes, please file an issue.

MCP server fails to start (Claude Code)

If the MCP server fails immediately after installation, uv is likely 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

Missing `unicode/uregex.h` (macOS)

On macOS, icu4c is keg-only (not in PATH by default). Solution:

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

Windows: Pure Go regex backend

Windows builds automatically use Go’s stdlib regexp instead of ICU to avoid CGO dependencies. If you need full ICU regex semantics, use Linux/macOS (or WSL on Windows) with ICU installed.

Updating Beads

Use the update command that matches how you installed:

brew upgrade beads

After Upgrading

Run these commands to check for updates and refresh hooks:

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

Next Steps

Quickstart

Get up and running in 2 minutes

Initialize Your Project

Run bd init to set up Beads in your project

Get Started

Core Concepts

Guides

Integrations

​Installing Beads

​Quick Install (Recommended)

​Shell Script

​Homebrew (Recommended)

​PowerShell Script

​Via go install

​Shell Script

​Via go install

​Package Managers

Homebrew

npm

Go

Arch Linux (AUR)

​Alternative Package Managers

​Mise-en-place

​Bun

​Building from Source

​Prerequisites

​Build Steps

​Installation Comparison

​Verify Installation

​IDE and Editor Integrations

​Claude Code / Cursor / Windsurf

​GitHub Copilot (VS Code)

​Claude Desktop (MCP-only)

​Troubleshooting

​bd: command not found

​zsh: killed bd (macOS crashes)

​MCP server fails to start (Claude Code)

​Missing unicode/uregex.h (macOS)

​Windows: Pure Go regex backend

​Updating Beads

​After Upgrading

​Next Steps

Quickstart

Initialize Your Project

Build docs developers (and LLMs) love

Installing Beads

Quick Install (Recommended)

Shell Script

Homebrew (Recommended)

PowerShell Script

Via go install

Shell Script

Via go install

Package Managers

Alternative Package Managers

Mise-en-place

Bun

Building from Source

Prerequisites

Build Steps

Installation Comparison

Verify Installation

IDE and Editor Integrations

Claude Code / Cursor / Windsurf

GitHub Copilot (VS Code)

Claude Desktop (MCP-only)

Troubleshooting

`bd: command not found`

`zsh: killed bd` (macOS crashes)

MCP server fails to start (Claude Code)

Missing `unicode/uregex.h` (macOS)

Windows: Pure Go regex backend

Updating Beads

After Upgrading

Next Steps