Beads (bd) – Distributed Issue Tracker for AI‑Agents

What it is – A command‑line tool that gives AI coding agents a structured, version‑controlled “memory” for tracking work. It stores tasks (called beads) in a Dolt SQL database, which behaves like a Git‑style data store with branching, merging and remote sync.

Why it matters for agents – Instead of scattering TODOs in markdown, agents can query a dependency graph, claim work atomically, and retrieve persistent facts (via bd remember). The JSON output and hash‑based IDs are designed for programmatic consumption, letting multiple agents collaborate without merge conflicts.

Core concepts

Concept	Explanation
Bead	A task/issue stored in the Dolt DB. IDs look like `bd‑a1b2` (epic) or `bd‑a1b2.1` (sub‑task).
Dependency graph	Tasks can be linked (`relates‑to`, `duplicates`, `supersedes`, `replies‑to`). `bd dep add <child> <parent>` creates blocker/parent relationships, enabling the `bd ready` command to list only work with no open blockers.
Dolt backend	Dolt provides a SQL database with cell‑level merges, native branches and remote push/pull. Beads can run Dolt embedded (default) or connect to an external Dolt SQL server for concurrent writers.
Agent‑optimized workflow	Commands emit JSON, support `--claim` (atomic claim + in‑progress flag), and expose a `bd prime` command that injects the project’s “memory” (facts, open tasks) into an agent’s prompt.
Compaction / memory decay	Closed tasks are summarised automatically so the database stays small and stays within LLM context windows.

Typical workflow (CLI commands)

# One‑time install (system‑wide)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialise a project (creates .beads/ and AGENTS.md)
cd my‑project && bd init

# Add a high‑priority task
bd create "Implement search endpoint" -p 0

# Declare that it blocks another task
bd dep add bd‑a1b2.1 bd‑a1b2   # child blocks parent

# Agent asks for work it can start now
bd ready --json   # only tasks with no open blockers

# Agent claims a task atomically
bd update bd‑a1b2.1 --claim

# While working, store a reusable insight
bd remember "ElasticSearch pagination uses `search_after`" 

# When finished, close the task (releases blockers)
bd close bd‑a1b2.1 "Implemented and tested"

bd prime prints the current context (open tasks, stored insights) so an LLM‑based coding assistant can prepend it to its prompt.

Integration points

Integration	What it adds
Codex / Claude / Factory.ai (`bd setup <name>`)	Installs language‑model‑specific instruction files (`AGENTS.md`) and IDE hooks so the model knows the Beads commands.
VS Code / Cursor / Copilot	Provides extensions that turn Beads commands into UI actions and automatically run `bd prime` before a generation.
HTTP backend (experimental)	Runs a thin client against a remote `bd serve` process, useful for shared servers or embedding Beads as a library.
Git‑free mode (`bd init --stealth`)	Stores everything in `.beads/` without touching the repository, ideal for CI, monorepos, or non‑Git VCS.

How it fits into an AI‑agent stack

Prompt preparation – bd prime (or the generated AGENTS.md snippet) injects a concise list of ready tasks and remembered facts into the LLM prompt.
Decision making – The agent parses the JSON output of bd ready/bd show to pick a task.
Execution – The agent runs bd update … --claim, performs code changes, then bd close ….
Collaboration – Multiple agents (or humans) can claim tasks concurrently; Dolt’s hash‑based IDs guarantee conflict‑free merges.
Persistence – All task history, dependencies and stored insights live in the Dolt DB and can be synced across machines with bd dolt push/pull.

Getting started

Install – brew install beads, npm install -g @beads/bd, or use the provided install script.
Docs – https://beads.gascity.com/ (installation, sync concepts, HTTP backend, troubleshooting).
Community – UI extensions, web front‑ends, and related projects are listed in docs/community-tools.md.

TL;DR

Beads is a purpose‑built issue tracker that turns a project’s task list into a machine‑readable, version‑controlled graph. By coupling it with LLM‑based coding agents, you get reliable, conflict‑free coordination and a durable “memory” that survives across runs and across multiple agents.

gastownhall/beads