Beads keeps agent work in a dependency graph instead of a checklist
Beads gives coding agents a persistent issue model with statuses, priorities, dependencies, parent-child relationships, claims, comments, and audit history. bd ready finds work with no open blockers, bd update --claim assigns it, and bd close releases downstream tasks. bd prime prints workflow context and remembered decisions into a new agent session. Hash-based IDs reduce collisions when separate branches create tasks.
The model is useful when work lasts longer than one context window or moves between agents. It also asks the team to treat task state as structured data. Agents must update records consistently, humans need commands or a community UI to inspect them, and project instructions must tell every participant that Beads exists. bd init writes or updates AGENTS.md by default and can install Claude and Codex integrations unless users choose stealth or skip-agent options.
Embedded Dolt supports one writer, while fleets need a server
The default database runs Dolt inside the bd process and stores data under .beads/embeddeddolt/. It requires no separate service, but it permits one writer at a time. Server mode connects multiple clients to dolt sql-server and stores data in a different project directory. That is the intended route for orchestrators or several agents writing concurrently.
Cross-machine sync uses bd dolt push and bd dolt pull against refs/dolt/data, separate from ordinary source branches. The JSONL file is an export for viewers, interchange, and migration. It cannot represent deletions reliably through upsert-only import and does not preserve Dolt branches, full history, working state, or non-issue tables. A backup uses bd backup, not a copied JSONL file.
What happened when we ran it
Our sandbox installed 668 Go packages in 117 seconds and built commit 62d2119 in 162 seconds. The checkout contained 3,635 files, roughly 837,819 lines of source, and occupied 36 MB. It had 18 CI workflow files and a tests directory. Our scan found no Dockerfile.
Tests ran for 464 seconds and exited with code 1. The harness recorded 133 passing and 17 failing groups out of 150. The supplied tail identifies github.com/steveyegge/beads/issueops as a build failure, then lists successful schema, scripts, migration, and documentation packages before the final failure. It does not show the compiler error or details for the remaining failed groups, so the measured conclusion is limited to an unclean suite.
The easiest install avoids the 668-package source build
Homebrew, npm, mise, and release scripts install the CLI without cloning the repository. The shell and PowerShell installers verify release checksums. Go installation has two distinct outputs: a no-CGO binary works only with an external Dolt server, while the CGO build includes embedded mode and needs a C compiler. Released Go modules retain the old github.com/steveyegge/beads path after the repository moved to gastownhall.
Claude Code can add a plugin with slash commands, while bd setup claude installs the normal CLI hooks. Codex setup writes a skill, AGENTS.md guidance, and native hooks. The MCP server is intended mainly for clients without shell access; the installation guide prefers the CLI for lower schema overhead and smaller context use. These paths can coexist, but most projects should pick one standard integration so agents receive the same instructions.
Version 1.2.2 is a rollback disguised as a forward release
The August 15, 2026 release is unusually candid. Versions 1.2.0 and 1.2.1 were published accidentally without release testing. Version 1.2.2 reissues tested 1.1.2 code under a higher number so package channels move forward. Features unique to the accidental line, including work leases, an event journal, sync federation, an HTTP API, and provenance events, are absent until they return through a tested release.
Running v1.2.1 once could migrate a local database from schema 53 to 65, leaving v1.2.2 unable to open it without recovery. The release directs users to roll back the schema cursor and warns that every machine must upgrade before recovery, or an old binary can silently migrate it again. That episode makes backups and coordinated upgrades mandatory for teams, not optional administration.
Parallel claim is not exclusive in the current server workflow
The README describes bd update --claim as atomic, but open issue 5998 reports a race in bd ready --claim. Two simultaneous v1.2.2 callers against one shared Dolt server both received the same bead, even though settled state later showed it claimed. The reporter uses a marker-comment arbitration workaround so only one worker proceeds.
That distinction matters for automated fleets. A database can end in one valid state while two agents already started the same expensive or conflicting work. Until a transactional compare-and-swap is verified, do not use the combined ready-and-claim command as the only dispatch lock. Add external arbitration, assign disjoint labels, or serialize dispatch. Also test failure recovery so a worker crash does not leave a task claimed forever.
Active development does not cancel the recovery cost
GitHub showed 26,631 stars, 796 combined issues and pull requests, and a last push on August 27, 2026. That is current activity, while the large queue reflects both scope and churn rather than 796 confirmed defects. Recent reports cover Windows backup URLs, empty-note replacement, concurrent claims, server status, and filesystem exhaustion.
Beads is appealing when agent continuity has become a larger problem than operating one more developer tool. The graph, readiness queries, audit trail, and session injection are better suited to long work than scattered Markdown. Our 17 failed groups and the recovery release argue for a controlled trial first. Pin binaries across machines, use a real Dolt backup, test a restore, and keep fleet dispatch guarded outside Beads until the claim race is closed.