gastownhall/beads

Beads - A memory upgrade for your coding agent

Summary

Beads (bd) is a distributed, dependency-aware graph issue tracker designed to give coding agents persistent, structured memory. It stores work in a Dolt-backed database rather than relying only on markdown plans, helping agents retain context across long-running tasks, branches, and machines. The project is written in Go and supports macOS, Linux, Windows, and FreeBSD.

What it is useful for

Beads is useful when an engineering team wants agents to manage a backlog instead of losing track of it inside a chat session or a growing set of TODO files. Tasks can be created, linked with dependencies, claimed atomically, inspected, and closed through the CLI:

• bd create "Title" -p 0 creates a priority-0 task.
• bd dep add <child> <parent> records blocking, related, or parent-child relationships.
• bd ready lists work whose open blockers have been resolved.
• bd update <id> --claim assigns a task and marks it in progress.
• bd show <id> displays details and an audit trail.
• bd close <id> completes a task.

It also provides durable project notes through bd remember "insight", which bd prime can later provide as workflow context. Hierarchical IDs support epics, tasks, and subtasks, while graph links can represent relationships such as relates-to, duplicates, supersedes, and replies-to.

The Dolt backend offers two documented storage modes. Embedded mode is the default and is recommended for most projects, but it is single-writer. Server mode uses an external dolt sql-server for multiple concurrent writers. Cross-machine synchronization uses bd dolt push and bd dolt pull. The HTTP backend is explicitly experimental and has documented differences from local operation, including refused or degraded behaviors for some commands.

How engineers can use it

Install the CLI once, then initialize it inside the project:

brew install beads
cd your-project
bd init

The README also documents npm install -g @beads/bd and a system-wide install script. bd init creates or updates AGENTS.md and installs supported agent integrations. Use bd setup --list to see available integrations, or set one up explicitly:

bd setup claude
bd setup codex
bd setup factory

A typical agent loop is to run bd prime, create or inspect issues with bd show, claim ready work with bd update <id> --claim, record useful context with bd remember, and finish with bd close.

For personal or shared-project work that should not add repository files, use bd init --stealth. Projects using another version-control system can set BEADS_DIR and initialize without Git, as documented in the README.