# bd - Beads

# bd - Beads

**Distributed graph issue tracker for AI agents, powered by [Dolt](https://github.com/dolthub/dolt).**

**Platforms:** macOS, Linux, Windows, FreeBSD

[![License](https://img.shields.io/github/license/gastownhall/beads)](LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/steveyegge/beads)](https://goreportcard.com/report/github.com/steveyegge/beads)
[![Release](https://img.shields.io/github/v/release/gastownhall/beads)](https://github.com/gastownhall/beads/releases)
[![npm version](https://img.shields.io/npm/v/@beads/bd)](https://www.npmjs.com/package/@beads/bd)
[![PyPI](https://img.shields.io/pypi/v/beads-mcp)](https://pypi.org/project/beads-mcp/)

**Docs:** https://gastownhall.github.io/beads/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

## Quick Start

```bash
# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: install richer instructions for your agent
bd setup codex    # Codex CLI - creates/updates AGENTS.md
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md
```

**Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

`bd init` creates or updates `AGENTS.md` by default so agents can discover the beads workflow. It skips agent files only when you pass `--skip-agents` or `--stealth`, or when you configure a custom agent file. Use `bd setup --list` to see supported integrations, including `bd setup codex`, `bd setup factory`, `bd setup claude`, `bd setup mux`, `bd setup cursor`, and more.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun `bd init`/`bd setup`, or custom instruction files. In those cases, run `bd onboard` and paste the printed snippet into the file your agent reads.

If your agent is not covered by `bd setup`, add this minimal `AGENTS.md` section:

```markdown
This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.
```

## Features

* **Dolt-Powered:** Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
* **Agent-Optimized:** JSON output, dependency tracking, and auto-ready task detection.
* **Zero Conflict:** Hash-based IDs (`bd-a1b2`) prevent merge collisions in multi-agent/multi-branch workflows.
* **Compaction:** Semantic "memory decay" summarizes old closed tasks to save context window.
* **Messaging:** Message issue type with threading (`--thread`), ephemeral lifecycle, and mail delegation.
* **Graph Links:** `relates_to`, `duplicates`, `supersedes`, and `replies_to` for knowledge graphs.

## Essential Commands

| Command | Action |
| --- | --- |
| `bd ready` | List tasks with no open blockers. |
| `bd create "Title" -p 0` | Create a P0 task. |
| `bd update <id> --claim` | Atomically claim a task (sets assignee + in_progress). |
| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
| `bd show <id>` | View task details and audit trail. |
| `bd prime` | Print agent workflow context and persistent memories. |
| `bd remember "insight"` | Store project memory that `bd prime` injects later. |

## Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

* `bd-a3f8` (Epic)
* `bd-a3f8.1` (Task)
* `bd-a3f8.1.1` (Sub-task)

**Stealth Mode:** Run `bd init --stealth` to use Beads locally without committing files to the main repo.

**Contributor vs Maintainer:**

* **Contributors** (forked repos): Run `bd init --contributor` to route planning issues to a separate repo (e.g., `~/.beads-planning`).
* **Maintainers** (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials.

## Installation

```bash
brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users
```

**Requirements:** macOS, Linux, Windows, or FreeBSD.

### Security And Verification

Before trusting any downloaded binary, verify its checksum against the release `checksums.txt`. The install scripts verify release checksums before install. On macOS, `scripts/install.sh` preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via `BEADS_INSTALL_RESIGN_MACOS=1`.

## Storage Modes

Beads uses Dolt as its database. Two modes available.

### Embedded Mode (default)

```bash
bd init
```

Dolt runs in-process — no external server needed. Data lives in `.beads/embeddeddolt/`. Single-writer only (file locking enforced).

### Server Mode

```bash
bd init --server
```

Connects to an external `dolt sql-server`. Data lives in `.beads/dolt/`. Supports multiple concurrent writers. Configurable via `--server-host`/`BEADS_DOLT_SERVER_HOST` (default `127.0.0.1`), `--server-port`/`BEADS_DOLT_SERVER_PORT` (default `3307`), `--server-socket`/`BEADS_DOLT_SERVER_SOCKET`, `--server-user`/`BEADS_DOLT_SERVER_USER` (default `root`), `BEADS_DOLT_PASSWORD`, and `BEADS_DOLT_CLI_DIR`.

Unix domain sockets via `--server-socket` avoid port conflicts and help in sandboxed environments (e.g., Claude Code) where file-level access control is simpler than network allowlists.

### Backup & Migration

```bash
bd backup init /path/to/backup
bd backup sync

bd init           # or bd init --server
bd backup restore --force /path/to/backup
```

## Git-Free Usage

```bash
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"
```

`BEADS_DIR` tells bd where to put the `.beads/` database directory, bypassing git repo discovery. `--stealth` sets `no-git-ops: true` in config.

Useful for: non-git VCS (Sapling, Jujutsu, Piper), monorepos (point `BEADS_DIR` at a subdirectory), CI/CD, ephemeral databases in `/tmp`.

For daemon mode without git, use `bd daemon start --local`.

## Repo metadata

- Stars: 23,236
- Language: Go (94.3%), with Python (3.0%), Shell (2.0%), JavaScript (0.3%)
- License: MIT
- Created: 2025-10-12
- Last push: 2026-05-06
- Releases: 89 (through v1.0.3)
- Distribution: Homebrew, npm (`@beads/bd`), PyPI (`beads-mcp`), install script
- Author: gastownhall (Steve Yegge — Go Report Card badge points at github.com/steveyegge/beads)