# Beads

> A dependency-graph issue tracker coding agents can claim work from

- Category: AI Coding / AI SDLC Automation
- Language: Go
- Licence: MIT
- Repository: https://github.com/gastownhall/beads
- Website: https://beads.gascity.com/
- Canonical page: https://ai-tldr.dev/tools/beads/
- Updated: 2026-04-24

## In short

Beads — the `bd` command — is a distributed graph issue tracker built for AI coding agents, powered by Dolt, the version-controlled SQL database. It sits in the AI SDLC Automation category of the AI Coding tools and is open-source, written in Go and licensed MIT. To get started: install the CLI.

## Overview

Beads — the `bd` command — is a distributed graph issue tracker built for AI coding agents, powered by Dolt, the version-controlled SQL database. It exists to replace the sprawling markdown plan files agents tend to write with a dependency-aware graph, so a long-horizon task survives the end of a context window: work is created as beads, linked by dependencies, and `bd ready` returns exactly the tasks that have no open blockers.

The design targets multi-agent and multi-branch work. Hash-based IDs such as `bd-a1b2` avoid merge collisions when several agents create issues at once, Dolt supplies cell-level merge, native branching and sync through Dolt remotes, and `bd update --claim` atomically assigns a task and moves it to in-progress so two agents do not pick up the same work. Hierarchical IDs (`bd-a3f8`, `bd-a3f8.1`, `bd-a3f8.1.1`) express epics, tasks and sub-tasks; graph links (`relates-to`, `duplicates`, `supersedes`, `replies-to`) turn the tracker into a small knowledge graph.

Beads is a CLI you install once and use across projects — the README is explicit that you should not clone the repository into your own. `bd init` sets up a project, writes or updates `AGENTS.md` so agents discover the workflow, and installs integrations; `bd setup` covers Codex, Claude Code, Factory.ai Droid, Cursor, mux and others. Beyond tasks, `bd remember` stores durable project memory that `bd prime` injects back at session start, and compaction summarises old closed work so the context window stays lean. A stealth mode keeps everything local when you would rather not commit tracker files to a shared repo.

## What it does

- Dolt-powered storage: a version-controlled SQL database with cell-level merge, native branching and sync over Dolt remotes
- Dependency graph with `bd ready` auto-detection of claimable, unblocked work, and atomic claiming via `bd update --claim`
- Hash-based IDs (`bd-a1b2`) so parallel agents and branches never collide on issue numbers
- Persistent project memory: `bd remember "insight"` stores it, `bd prime` injects it plus workflow context at session start
- Compaction — semantic memory decay that summarises old closed tasks to save context window
- One-command agent integration through `bd setup` for Codex, Claude Code, Factory, Cursor and more, plus an npm package and a `beads-mcp` PyPI package

## Getting started

Beads is a system-wide CLI available for macOS, Linux, Windows and FreeBSD. Install it once, then initialise it inside each project you want tracked.

1. Install the CLI

   Homebrew is the recommended route; an npm package and an install script are also published.

```bash
brew install beads
# or
npm install -g @beads/bd
```

2. Initialise it in your project

   Run `bd init` from your own repository — not from a clone of the Beads repo. It creates or updates AGENTS.md so agents discover the workflow, and installs project integrations unless you pass --skip-agents or --stealth.

```bash
cd your-project
bd init
```

3. Wire up your agent

   Install richer instructions, hooks and skills for the agent you use. `bd setup --list` shows every supported integration.

```bash
bd setup claude    # Claude Code — hooks/settings
bd setup codex     # Codex CLI — skill, AGENTS.md guidance, hooks
bd setup factory   # Factory.ai Droid — creates/updates AGENTS.md
```

4. Work the graph

   Create tasks, link dependencies, and let the agent claim whatever is ready.

```bash
bd create "Title" -p 0
bd dep add <child> <parent>
bd ready
bd update <id> --claim
bd show <id>
bd close <id>
```

## When to use it

- Give a coding agent long-horizon work it can resume: a dependency graph of tasks instead of a markdown TODO that falls out of context
- Run several agents or branches against the same backlog without merge collisions on issue IDs
- Keep durable project decisions where the agent will actually see them, via `bd remember` and `bd prime`
- Track personal planning on a shared repository without committing tracker files, using `bd init --stealth`

## Version history

- 2026-04-24: AI/TLDR covered Beads as a git-backed dependency-graph issue tracker built for AI coding agents: a Dolt-backed graph with hash IDs that avoid multi-agent merge conflicts, semantic memory decay, and ready-task injection at session start.