beads/docs/INSTALLING.md

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

Typical setups:

Environment	What to Install
Claude Code, Cursor, Windsurf	bd CLI (+ optional Plugin for Claude Code)
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

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)
• Install via go install if Go is available
• Fall back to building from source if needed
• Guide you through PATH setup if necessary

Comparison of Installation Methods

Method	Best For	Updates	Prerequisites	Notes
Homebrew	macOS/Linux users	brew upgrade bd	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	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

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

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.exe ./cmd/bd
Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\

Verify installation:

bd version

Windows notes:

• The background daemon listens on a loopback TCP endpoint recorded in .beads\bd.sock
• Keep that metadata file intact
• Allow bd.exe loopback traffic through any host firewall

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

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

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.

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

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:

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

Homebrew

brew upgrade 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/

Uninstalling

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