Installation

Install Beads on macOS, Linux, Windows, or FreeBSD via Homebrew, npm, Go, or shell script

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

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

Windows

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.

FreeBSD

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

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

Ubuntu / Debian

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

Fedora / RHEL

sudo dnf install -y libicu-devel libzstd-devel

Windows

No system dependencies required! Windows builds use pure Go regex automatically.

Build Steps

1. Clone the repository

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

   macOS / Linux

   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).

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

1. Install beads-mcp

   uv tool install beads-mcp
   # or
   pip install beads-mcp
   
2. 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

3. Initialize project

   bd init --quiet
   
4. 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:

1. Install beads-mcp

   uv tool install beads-mcp
   
2. Configure Claude Desktop

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

   {
     "mcpServers": {
       "beads": {
         "command": "beads-mcp"
       }
     }
   }
   
3. 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:

Homebrew

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