beads

Beads gives coding agents a structured alternative to markdown TODO lists. Tasks, blockers, messages, and durable project facts are stored in a Dolt version-controlled SQL database, while a dependency graph determines which work is ready to claim. The `bd` command-line interface supports the core workflow: initialize a project with `bd init`, create tasks, add dependencies, list unblocked work with `bd ready`, atomically claim work with `bd update --claim`, inspect details and audit history with `bd show`, and finish items with `bd close`. `bd prime` supplies workflow context and stored memories to an agent, and `bd remember` saves durable project facts. Beads uses hash-based IDs such as `bd-a1b2` and supports hierarchical epic/task/subtask IDs. It includes JSON output for agents, automatic ready-task detection, priority values, graph relationships such as `relates-to`, `duplicates`, `supersedes`, and `replies-to`, plus threaded message issues with an ephemeral lifecycle. A compaction feature summarizes older closed tasks to reduce the context agents must load. Dolt provides branching, cell-level merge behavior, and synchronization through remotes. The default embedded mode runs Dolt in process with a single writer; server mode connects to an external `dolt sql-server` for concurrent writers. Cross-machine synchronization uses `bd dolt push` and `bd dolt pull`. The repository also documents backup, pruning, purging, schema-version checks, migration procedures, and an escape hatch for schema skew. Agent setup is available through `bd setup` for supported tools such as Codex CLI, Claude Code, Factory.ai, Cursor, and others. Initialization can add `AGENTS.md` guidance and hooks, while `bd onboard` prints a snippet for unsupported agents. Beads can also run without Git using `BEADS_DIR` and `--stealth`, making it usable with non-Git version control systems, monorepos, CI environments, and temporary databases. The project supports macOS, Linux, Windows, and FreeBSD. Installation options include Homebrew, npm, an install script, Go installation, source builds, and platform-specific packages. The README advises verifying release checksums before trusting downloaded binaries.