gastownhall/beads

If you already hand a coding agent a long job and watch it lose the thread between sessions, Beads is worth an hour of evaluation. It swaps your markdown plan for a small database-backed issue graph the agent can query.

The problem

A user opens an agent session with a multi-step plan and wants the work to survive context resets, new branches and a second machine. Today that plan usually lives in a markdown file or a chat summary: the agent has to re-read the whole thing, cannot tell what is actually unblocked, and two agents editing the same file collide. With Beads, the plan becomes rows in a Dolt database: the agent runs bd ready to see claimable work, bd update --claim to take an item, and bd close to finish it, at which point blocked children become ready. The result is a persistent task state that outlives the conversation rather than a document that has to be re-parsed.

What's different

Beads is built on Dolt, a version-controlled SQL database with cell-level merge and native branching, and syncs with bd dolt push / bd dolt pull. That choice is the real differentiator: task state is queryable and mergeable like data, and hash-based IDs (bd-a1b2) avoid collisions when multiple agents or branches create items independently. The README also describes compaction that summarizes old closed tasks to save context window, and extra issue types for threaded messages and graph links such as relates-to and supersedes. In practice, an agent can ask for exactly the ready set instead of being handed the entire backlog in its prompt.

The trade-off is that you are adopting a database, not a text file: storage modes differ (embedded single-writer by default, or a dolt sql-server for concurrent writers), cross-machine work depends on Dolt remotes, and upgrades can involve schema migrations. That is more machinery than a markdown plan, and the sync and sharing parts only pay off if you actually work across agents, branches or machines.

Who should try it

Good fit: a developer already running coding agents (Claude Code, Codex, Cursor, Factory) on long-horizon or multi-session work, who wants the agent to pick up blocked and ready tasks without re-reading a plan. It is also a reasonable fit for a shared project where you want local tracking without committing Beads files, via bd init --stealth. Poor fit: someone who just wants a scratchpad inside one chat session, or a team that will not maintain a shared Dolt remote. Git is optional: BEADS_DIR plus --stealth works with non-git VCS or CI.

Requirements and limitations

A supported OS is macOS, Linux, Windows or FreeBSD, and the install is one CLI plus bd init in your project, which by default edits AGENTS.md and installs integrations unless you pass --skip-agents or --stealth. The deeper constraints are ongoing: embedded mode is single-writer, so several concurrent agents need server mode; sharing across machines means maintaining a Dolt remote; and binaries must match the database schema, with a stale binary exiting on a version mismatch. Upgrades need a documented order: export, replace the binary, run bd info --whats-new and bd hooks install, and for remote-backed databases designate one clone to migrate and push. The HTTP backend for shared servers is marked experimental. Read the installation and upgrade guides before committing a team.

HotRepo's take

HotRepo's records cover two daily-board appearances, 2026-10-24 (+29 stars) and 2026-10-25 (+30); there is no comparable earlier history, so persistence of interest cannot be judged from that sample. The project is about a year old. Before adopting, verify the upgrade path for a remote-backed database on the version you will pin.