> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Quick Install (Recommended)

<Tabs>
  <Tab title="macOS / Linux">
    ### Shell Script

    ```bash theme={null}
    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)

    ```bash theme={null}
    brew install beads
    ```

    **Why Homebrew?**

    * ✅ Simple one-command install
    * ✅ Automatic updates via `brew upgrade`
    * ✅ No need to install Go
    * ✅ Handles PATH setup automatically
  </Tab>

  <Tab title="Windows">
    ### PowerShell Script

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
    ```

    **Prerequisites:**

    * [Go 1.24+](https://go.dev/dl/) installed
    * Git for Windows
    * Add `%USERPROFILE%\go\bin` to your PATH

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

    ### Via go install

    ```powershell theme={null}
    go install github.com/steveyegge/beads/cmd/bd@latest
    ```

    <Tip>
      ICU is **not required** on Windows. The regex backend uses pure Go automatically.
    </Tip>
  </Tab>

  <Tab title="FreeBSD">
    ### Shell Script

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
    ```

    ### Via go install

    ```bash theme={null}
    go install github.com/steveyegge/beads/cmd/bd@latest
    ```
  </Tab>
</Tabs>

## Package Managers

<CardGroup cols={2}>
  <Card title="Homebrew" icon="beer-mug">
    ```bash theme={null}
    brew install beads
    ```

    Works on macOS and Linux.
  </Card>

  <Card title="npm" icon="node-js">
    ```bash theme={null}
    npm install -g @beads/bd
    ```

    Convenient for JavaScript/Node.js projects.
  </Card>

  <Card title="Go" icon="golang">
    ```bash theme={null}
    go install github.com/steveyegge/beads/cmd/bd@latest
    ```

    Requires Go 1.24+. Builds from source.
  </Card>

  <Card title="Arch Linux (AUR)" icon="linux">
    ```bash theme={null}
    yay -S beads-git
    # or
    paru -S beads-git
    ```

    Community-maintained by [@v4rgas](https://github.com/v4rgas).
  </Card>
</CardGroup>

### Alternative Package Managers

#### Mise-en-place

[Mise](https://mise.jdx.dev) works on all platforms and supports version management:

```bash theme={null}
# 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
```

<Tip>
  The `-g` flag enables Beads globally. Omit it for project-specific versions.
</Tip>

#### Bun

```bash theme={null}
bun install -g --trust @beads/bd
```

## Building from Source

### Prerequisites

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

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install icu4c zstd
    ```

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

    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Ubuntu / Debian">
    ```bash theme={null}
    sudo apt-get install -y libicu-dev libzstd-dev
    ```
  </Tab>

  <Tab title="Fedora / RHEL">
    ```bash theme={null}
    sudo dnf install -y libicu-devel libzstd-devel
    ```
  </Tab>

  <Tab title="Windows">
    No system dependencies required! Windows builds use pure Go regex automatically.
  </Tab>
</Tabs>

### Build Steps

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/steveyegge/beads
    cd beads
    ```
  </Step>

  <Step title="Build">
    <CodeGroup>
      ```bash macOS / Linux theme={null}
      go build -o bd ./cmd/bd
      sudo mv bd /usr/local/bin/
      ```

      ```powershell Windows theme={null}
      go build -tags gms_pure_go -o bd.exe ./cmd/bd
      Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\
      ```
    </CodeGroup>

    <Note>
      On Windows, the `-tags gms_pure_go` flag enables pure Go regex (no ICU needed).
    </Note>
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    bd version
    bd help
    ```
  </Step>
</Steps>

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

<Tip>
  **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.
</Tip>

## Verify Installation

After installing, verify Beads is working:

```bash theme={null}
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:

```bash theme={null}
# 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:**

```bash theme={null}
bd setup claude --check
bd setup cursor --check
```

### GitHub Copilot (VS Code)

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

<Steps>
  <Step title="Install beads-mcp">
    ```bash theme={null}
    uv tool install beads-mcp
    # or
    pip install beads-mcp
    ```
  </Step>

  <Step title="Configure MCP">
    Create `.vscode/mcp.json` in your project:

    ```json theme={null}
    {
      "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`                     |
  </Step>

  <Step title="Initialize project">
    ```bash theme={null}
    bd init --quiet
    ```
  </Step>

  <Step title="Reload VS Code">
    Restart VS Code to load the MCP server.
  </Step>
</Steps>

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

### Claude Desktop (MCP-only)

For environments without shell access:

<Steps>
  <Step title="Install beads-mcp">
    ```bash theme={null}
    uv tool install beads-mcp
    ```
  </Step>

  <Step title="Configure Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

    ```json theme={null}
    {
      "mcpServers": {
        "beads": {
          "command": "beads-mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Close and reopen Claude Desktop to load the MCP server.
  </Step>
</Steps>

## Troubleshooting

### `bd: command not found`

Beads is not in your PATH. Either:

```bash theme={null}
# 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:**

```bash theme={null}
# 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/
```

<Note>
  If you installed via Homebrew, CGO is already enabled. If you're still seeing crashes, please [file an issue](https://github.com/steveyegge/beads/issues).
</Note>

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

```bash theme={null}
# 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:**

```bash theme={null}
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:

<CodeGroup>
  ```bash Homebrew theme={null}
  brew upgrade beads
  ```

  ```bash npm theme={null}
  npm update -g @beads/bd
  ```

  ```bash bun theme={null}
  bun install -g --trust @beads/bd
  ```

  ```bash go install theme={null}
  go install github.com/steveyegge/beads/cmd/bd@latest
  ```

  ```bash Shell script (macOS/Linux) theme={null}
  curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
  ```

  ```powershell PowerShell (Windows) theme={null}
  irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
  ```

  ```bash From source theme={null}
  cd beads
  git pull
  go build -o bd ./cmd/bd
  sudo mv bd /usr/local/bin/
  ```
</CodeGroup>

### After Upgrading

Run these commands to check for updates and refresh hooks:

```bash theme={null}
bd info --whats-new
bd hooks install
bd version
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get up and running in 2 minutes
  </Card>

  <Card title="Initialize Your Project" icon="terminal" href="/quickstart#initialize-beads">
    Run `bd init` to set up Beads in your project
  </Card>
</CardGroup>