# bd (Beads): a Dolt-backed issue graph as memory for coding agents > Beads replaces markdown planning files with a dependency-aware issue graph stored in Dolt. It is aimed at people running long agent sessions, and its install is a single curl script or brew formula. **gastownhall/beads** — Beads - A memory upgrade for your coding agent. bd - Beads Distributed graph issue tracker for AI agents, powered by Dolt.** Platforms:** macOS, Linux, Windows, FreeBSD Docs:** Beads provides a persistent, structured memory for coding agents. - Repository: https://github.com/gastownhall/beads - Website: https://beads.gascity.com - Stars: 27,471 · Forks: 1,858 - Language: Go - License: MIT - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/gastownhall-beads ## What Beads replaces, and who ends up using it The README frames the problem narrowly: agents lose context on long-horizon tasks, and the usual workaround is a markdown plan file that drifts. Beads swaps that file for a dependency graph. Each unit of work is a bead with an ID, a priority, blockers and an audit trail, and the graph is stored in Dolt rather than in text. The audience is specific. You are running a coding agent such as Codex CLI, Claude Code or Factory.ai Droid, and the work spans more than one session. The README's own setup commands, bd setup codex, bd setup claude and bd setup factory, name those integrations directly. A solo developer filing three tickets a week gets little from this. Someone coordinating several agents on one repository, where two of them might otherwise pick up the same task, is the intended user. One detail signals the design target. IDs are hash-based, written as bd-a1b2, and the README says this prevents merge collisions in multi-agent and multi-branch workflows. Sequential numbering would collide the moment two branches create task 42. That choice only matters if you actually run parallel agents or branches, which tells you who the project is built for. ## How the Dolt graph and the ready queue actually work The README's flow diagram is the clearest description of the mechanism: bd create makes a bead, it enters the dependency graph, bd ready lists work with no open blockers, bd update --claim takes it atomically, and bd close releases whatever it was blocking back into the ready queue. The loop is the product. Nothing here is a document you read; it is a queue you draw from. Underneath, Dolt supplies version control over SQL tables, with cell-level merge and native branching, and sync through Dolt remotes. The README's diagram shows bd dolt push and bd dolt pull as the link to other machines and agents. So the persistence story is not a JSON file in a git repo. It is a database with its own remote and its own merge semantics. Two storage modes are documented. Embedded is the default: bd init runs Dolt in-process, data lives in .beads/embeddeddolt/, and there is a single writer. Server mode, bd init --server, connects to an external dolt sql-server for multiple concurrent writers. The README is truncated at exactly that sentence, so the concurrency behaviour of server mode is not spelled out in the visible documentation. Treat the embedded single-writer constraint as real: it is the default, and it is the mode most people will land in. Two more mechanisms deserve naming. Compaction summarizes old closed tasks, which the README calls semantic memory decay, to keep the context window from filling with finished work. And bd remember stores an insight that bd prime injects later, which is the actual persistent memory feature rather than the issue tracker part. ## Installing bd and running your first real task The README is explicit that Beads is a CLI you install once, not a repository you clone into your project. The quick-start script is the generic path: ```bash curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ``` The README states the install scripts verify release checksums before installing, so the pipe-to-bash pattern here is at least checked against a published checksums.txt. If you prefer a package manager, brew install beads is listed as recommended for macOS and Linux, and npm install -g @beads/bd covers Node.js users. The README also points to go install, a source build, Windows, and Arch AUR under other methods. Then initialize inside your own project, not inside a checkout of Beads: ```bash cd your-project bd init ``` According to the README, bd init creates or updates AGENTS.md so agents can discover the workflow, and installs project Claude and Codex integrations unless you pass --skip-agents or --stealth. If you want the agent-side wiring done explicitly instead, the setup subcommands are the documented route: ```bash bd setup codex # Codex CLI - installs skill, AGENTS.md guidance, and hooks bd setup claude # Claude Code - installs hooks/settings bd setup factory # Factory.ai Droid - creates/updates AGENTS.md ``` From there the working loop is four commands. Create a task, ask what is unblocked, claim one, close it: ```bash bd create "Wire up the export endpoint" -p 0 bd ready bd update bd-a1b2 --claim bd close bd-a1b2 ``` The README describes --claim as atomic, setting assignee and in_progress together, which is what stops two agents from grabbing the same bead. After that, bd prime prints workflow context and stored memories, and bd remember stores one. If your agent is not covered by bd setup, the README says to run bd onboard and paste the printed snippet into the file your agent reads. ## Upgrades are not a binary swap, and that is a real cost Most CLI tools treat an upgrade as replacing a file. Beads does not, and the README says so plainly: replacing the binary is not always the whole story. The documented sequence is to sync remote-backed databases with your current bd, back up with bd export --all, upgrade the binary, then run bd info --whats-new, bd hooks install and bd version. The part that should slow you down is the schema migration case. If the upgrade crosses a migration on a remote-backed database, the README states that exactly one designated clone runs bd migrate and bd dolt push, while other clones install the new binary and run bd bootstrap. That is a coordination requirement, not a suggestion. On a team where several people upgrade whenever they feel like it, this is the failure mode: divergent schema state across clones, repaired by hand. The embedded single-writer default compounds it. If your team commits .beads/ and everyone runs embedded Dolt, you have many writers over time and one writer at any moment, each holding a local copy of a versioned database. The README does not document rollback, so if a migration goes wrong there is no documented undo path. Backing up with bd export --all before upgrading is the mitigation the README itself recommends, and it is worth treating as mandatory rather than optional. ## When Beads is the wrong tool If your tracker needs to be read by someone who will never open a terminal, Beads is the wrong choice. There is no web UI described in the README, no board, no comment thread a product manager can browse. The interface is the bd CLI and whatever your agent reads from AGENTS.md. A team that lives in Jira or Linear for stakeholder visibility should keep doing that. The second case is a repository where you cannot commit .beads/. Beads wants its database in the project, and the README offers bd init --stealth for using it locally without committing files to the main repo. That works for personal use on a shared project, but it also means the memory is not shared, which removes a large part of the point. If your reason for wanting Beads is coordination between people, stealth mode does not deliver it. The third case is a project with no agent in the loop. Beads is described as persistent structured memory for coding agents. Without an agent consuming bd prime and bd ready, you have adopted a Dolt database and a CLI to maintain a task list you could keep in a text file, and you have taken on the migration and single-writer constraints for nothing. The README's own instruction not to use markdown TODO lists is addressed to agents, not to humans who happen to like markdown. Finally, contributors on forked repositories get a different data path. The README says bd init --contributor routes planning issues to a separate repo such as ~/.beads-planning, keeping experimental work out of pull requests. That is a deliberate split, and if you expected your fork's beads to travel with the PR, they will not. ## Alternatives, and where the approach actually differs The nearest comparison is the plain markdown plan the README sets out to replace. A TODO.md file is readable in any editor, diffs cleanly, and needs no install. It also has no notion of blocking: nothing stops an agent from starting step four before step two, and nothing prevents two agents from editing the same lines. Beads answers both with the dependency graph and atomic --claim. The cost is that your plan is now a database you upgrade carefully. Against a hosted tracker like Linear or Jira, the difference is where state lives and who can reach it. Beads keeps the graph inside the repository, versioned with Dolt, and syncs through Dolt remotes rather than a vendor API. That is why bd dolt push exists at all. The trade is that you own the sync, and the README's migration rules apply to you. The repository also contains a linear-workflow example under examples/, which suggests the project expects people to arrive from that direction. A third option is the agent framework's own memory. Several agent tools ship some form of notes or scratchpad. Beads differs by making the unit a bead with an ID, a priority and links, including the graph link types the README lists: relates-to, duplicates, supersedes and replies-to. Those link types are what turn a task list into something closer to a knowledge graph, and a scratchpad does not give you that. Whether you need it depends on whether your work has dependencies worth modelling. ## Licence and what the repository tells you about maintenance Beads is MIT licensed, and the repository carries a THIRD_PARTY_LICENSES file alongside LICENSE. That matters more than usual here because the dependency list in go.mod is long and includes Dolt, the Anthropic SDK, OpenTelemetry, SQLite bindings and testcontainers. MIT on the project does not relicense those; if you are redistributing a binary, the third-party file is the one to read. This is not legal advice, and the repository's own THIRD_PARTY_LICENSES is the authoritative list. On activity: the repository is not archived, and the last push was on 2026-08-15, which is the same date as the v1.2.2 release. That is the most recent fact available. The release history shows v1.2.2-rc.1 earlier the same day and v1.2.1 on 2026-08-11, so the project was cutting releases in quick succession in that window. The repository layout is worth noting for anyone judging maturity. There are PROPOSAL files for pluggable storage backends, CAS conditional update and a pull-config wedge, plus a FEDERATION-SETUP.md and a BENCHMARKS.md. Proposals sitting in the tree mean those capabilities are not shipped. If you need a storage backend other than Dolt, or federation between separate Beads instances, the presence of those files is evidence of intent, not of a feature you can use today. ## Conclusion Adopt Beads if you run agents across multi-step work and your task list has outgrown a markdown file, and you are willing to accept a Dolt database inside .beads/ as part of the project. Skip it if you want a shared tracker that a non-technical teammate can edit in a browser, or if you cannot commit .beads/ to the repository and do not want stealth mode. Before you rely on it, run bd info --whats-new and bd version after upgrading, and check whether your remote-backed database crosses a schema migration, because the README states exactly one designated clone must run bd migrate and bd dolt push in that case. ## FAQ ### How do I use beads with my coding agent? Install the CLI, run bd init inside your project, then run the setup command for your agent, such as bd setup codex, bd setup claude or bd setup factory. The README says bd init creates or updates AGENTS.md so agents can discover the workflow, and bd prime prints the workflow context and stored memories. ### How do I install beads? The README lists brew install beads for macOS and Linux, npm install -g @beads/bd for Node.js users, and a quick-start script at https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh. It also points to go install, a source build, Windows and Arch AUR under other methods. ### What is the Beads AI issue tracker for? Beads provides persistent, structured memory for coding agents, replacing markdown plans with a dependency-aware graph so agents can handle long-horizon tasks without losing context. Tasks are created, claimed and closed through the bd CLI. ### Does Beads need a separate database server? No. Embedded mode is the default, where bd init runs Dolt in-process and data lives in .beads/embeddeddolt/ with a single writer. Server mode, bd init --server, connects to an external dolt sql-server for multiple concurrent writers. ### What happens to my Beads data when I upgrade bd? The README says replacing the binary is not always the whole story: sync remote-backed databases, back up with bd export --all, upgrade, then run bd info --whats-new, bd hooks install and bd version. If the upgrade crosses a schema migration on a remote-backed database, exactly one designated clone runs bd migrate and bd dolt push while other clones run bd bootstrap. ## Sources - [Official documentation](https://beads.gascity.com) - [Official README](https://github.com/gastownhall/beads#readme) - [Project repository](https://github.com/gastownhall/beads) - [Release notes](https://github.com/gastownhall/beads/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gastownhall-beads