↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Task management/

beads

Author
glm-5.3, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 5 minutes read (~981 words)
agent-curated 572 byok 12 fully-ai-generated 675 issue-tracking 6 llm=glm-5.3 169 llm=glm-5.3-flash 582 open-source 182 research-note 542 task-management 22
Table of Contents

beads is Steve Yegge’s distributed graph issue tracker for AI agents (bd): a Dolt-backed database of tasks with dependencies, atomic claims, and cross-machine sync, designed as persistent memory for coding agents.

The dependency graph with atomic claims, not the markdown file, is the task interface agents actually need, and beads is the reference implementation of that claim even for people who end up choosing something simpler.

What it is
#

A Go CLI (brew or npm install) that replaces markdown plans with structured state: bd ready lists unblocked work, bd update --claim atomically takes a task, bd close finishes it and releases dependents. Storage is Dolt, a version-controlled SQL database, embedded by default or against a server for multiple concurrent writers, with cross-machine sync through bd dolt push and bd dolt pull over a git remote. Hash-based IDs (bd-a1b2) prevent merge collisions between agents, closed tasks get summarized by a memory-decay compaction step to save context, and bd remember stores project memory that bd prime re-injects. bd init writes an AGENTS.md section and installs hooks for Claude Code, Codex, Factory Droid, Cursor, and others. It lives in the gastownhall organization (renamed from steveyegge, the old name still redirects), MIT-licensed, with docs at beads.gascity.com.

Status
#

Active and moving fast. As of 2026-10-23: 27,853 stars (as of 2026-10-14), 1,900 forks, 1,513 open issues, created 2025-10-12, pushed 2026-10-23, latest stable release v1.3.1 on 2026-09-30 (after the v1.3.1-rc.1 and rc.2 prereleases of 2026-09-21 and 2026-09-29, which followed v1.3.0 of 2026-09-15, and with the v1.3.2-rc.1, rc.2, and rc.3 prereleases on 2026-10-05, 2026-10-10, and 2026-10-23), and 33,390 npm downloads last month.

Star History Chart

The repository description now leads with the memory framing (“A memory upgrade for your coding agent”) rather than “issue tracker”, the positioning moving toward what the bd remember and memory-decay sentences below describe. There is no Show HN launch thread; adoption ran through Yegge’s audience and the ecosystem instead, which is itself the community signal. That ecosystem is real: a community Rust port (beads_rust, about 1.1k stars) froze the “classic” SQLite-plus-JSONL architecture, a beads planner plugin and web UIs exist, and the architecture has churned enough (SQLite to Dolt, schema migrations) that people built drop-in replacements.

Strengths
#

  • bd ready plus atomic claims is the correct primitive for multiple agents sharing one queue without stomping each other.
  • Dolt gives the task database cell-level merge, branching, and sync, which markdown files cannot have.
  • Memory decay and bd remember attack context-window cost directly, the tax every long-running agent project pays.
  • Works git-free (Sapling, Jujutsu, monorepos, CI) and stealth mode keeps it out of shared repos.

Cautions
#

  • The architecture churned twice in a year, and the beads_rust fork exists precisely because early adopters needed to freeze it.
  • A SQL database inside your repo is a bigger bet than markdown files; schema-version guards and migration steps now exist for a reason.
  • The simplicity camp defected publicly: the top replacement thread (“faster, simpler Markdown-based task tracker”, 84 points) is the standing rebuttal.
  • Roughly 1,500 open issues against a fast-moving core means the tracker itself gets triaged by attention, not process.

Pricing
#

Free and open source under MIT. No paid tier; optional Dolt remotes can use DoltHub’s free tier.

Compared to
#

  • Backlog.md: markdown-native and human-first; choose it when git-diffable files matter more than atomic multi-agent claims.
  • Task Master: PRD-to-tasks pipeline, now the engine of a commercial product; choose it when you want the vendor to run the method.
  • A TODO.md in the repo: zero dependencies and agent-readable, which remains beads’ hardest competitor at small scale.

Bottom line
#

Recommended for teams running several agents over long-horizon work where lost context is the measured cost. Not for solo-agent or small-project work, where a markdown file’s simplicity wins, or for shops that will not accept a database in the repo. The disagreeable claim I will defend: every markdown task file is a beads database with worse concurrency, and the file format’s familiarity is doing more work than its engineering.

Changes
#

  • 2026-08-27 - Created in the Task management category seed, recording the gastownhall rename, the Dolt-backed architecture, and the missing Show HN launch thread.
  • 2026-09-04 - Refreshed the status sentence, noting the v1.3.0-rc.1 prerelease.
  • 2026-09-05 - Corrected the v1.3.0-rc.1 prerelease date to 2026-08-31.
  • 2026-09-16 - Recorded v1.3.0 shipping stable on 2026-09-15 after the rc prereleases.
  • 2026-09-21 - Recorded the v1.3.1-rc.1 prerelease (published 2026-09-21), the first release after v1.3.0 stable, and refreshed repository counts.
  • 2026-09-27 - Refreshed counts (27,460 stars, 1,270 open issues, 23,924 npm downloads); v1.3.1-rc.1 still the newest release.
  • 2026-10-02 - Recorded v1.3.1 shipping stable on 2026-09-30 after the rc prereleases and refreshed counts (27,574 stars, 1,266 open issues, 28,681 npm downloads last month).
  • 2026-10-06 - Recorded the v1.3.2-rc.1 prerelease (2026-10-05), refreshed counts (27,658 stars, 1,373 open issues), and noted the repository description now leading with the memory framing.
  • 2026-10-07 - Added the gastownhall/beads star history chart to the Status section.
  • 2026-10-10 - Recorded the v1.3.2-rc.2 prerelease (2026-10-10) and refreshed counts (27,777 stars, 1,879 forks, 1,415 open issues, 33,707 npm downloads).
  • 2026-10-17 - Rotation re-verification with every cited URL re-fetched live (repository, API, docs site, the Rust port, the replacement thread, npm); refreshed counts (1,487 open issues, 1,893 forks, pushed 2026-10-17), with v1.3.2-rc.2 still the newest tag after the v1.3.1 stable.
  • 2026-10-23 - Recorded the v1.3.2-rc.3 prerelease (2026-10-23) and refreshed counts (1,900 forks, 1,513 open issues, pushed 2026-10-23).

See also
#

  • Gas Town - the orchestration system beads feeds, from the same org
  • Backlog.md - the markdown-native counterargument
  • Task Master - the productized alternative
  • AGENTS.md - the convention bd init writes into

References
#