Workfile vs Beads
Every claim about a third party below links its source and was checked on .
Beads (bd) is an issue tracker built for coding agents: one Go binary, issues in a Dolt database, a ready queue computed from its blocking dependencies (four of its nineteen dependency types), and a claim that refuses an issue someone else holds. Workfile keeps its records as Markdown files in the repository instead of a database, scopes a claim to paths and keeps enforcing it after the claim, and refuses done while an acceptance criterion is unchecked. Beads is far more widely used and has the richer dependency model; it also sends usage metrics unless they are turned off.
Read against Beads v1.2.2 — its latest stable release, from 2026-08-15 — at commit 6c12420, and @illodev/workfile 0.13.2. The metrics were also observed in the released binary, not only read in the source. The repository has moved from steveyegge/beads to gastownhall/beads.
Side by side
| Workfile 0.13.2 | Beads 1.2.2 | |
|---|---|---|
| Records live in | Markdown files in .project/, versioned by git |
A Dolt database, embedded by default under .beads/embeddeddolt/; issues.jsonl is an export (README, sync) |
| Record types | Cards, docs, changelog fragments and releases, typed memory | Issues of twelve built-in types, including epic, decision and gate (types); nineteen dependency types (dependencies); key-value memories (memory) |
| Who holds work | A claim over paths; another actor's transition or release is refused; Claude Code asks before an edit in the scope | Claiming an issue someone else holds is refused (claim); afterwards bd update --assignee overwrites the holder (update) and bd close does not check it |
| Done with criteria unchecked | Refused with CARD_ACCEPTANCE_UNMET |
Allowed: acceptance_criteria is free text that bd close does not read. Close does refuse epics with open children, unresolved gates and open blockers, unless --force is given (close) |
| Changelog | Fragments cut into releases | None for projects; per-issue history from Dolt (history) |
| MCP server | workfile mcp, in the same package, 32 tools |
beads-mcp, a separate Python ≥ 3.10 package that calls the bd CLI, 15 tools (server, package) |
| UI | Local web UI | None built in; bd graph --html and community UIs (list) |
| Usage data by default | None; one npm version check a day, removed by upgrade: { check: false } |
Usage metrics on unless disabled: each command's name with the bd version, OS, timestamps and an HMAC-hashed machine ID; bd metrics off or BD_DISABLE_METRICS=1 (payload, default, off) |
| Runtime | Node.js ≥ 22 | A single Go binary through Homebrew, npm, go install, AUR or an install script (README) |
| License | MIT | MIT |
Where Beads is stronger
- Adoption. 27,150 GitHub stars (GitHub), packages on Homebrew, npm and AUR, and more than ten community UIs and editor extensions.
- No runtime to install. A single Go binary; Workfile needs Node.js 22.
- Claim the next ready issue in one step.
bd ready --claimpicks and claims in one transaction (issues.go);bd close --claim-nextcloses, then claims the top ready issue (close). - The dependency graph. Nineteen dependency types, four of which gate the ready queue (types), templates that create whole graphs, and an HTML graph.
- Gates that check themselves. A CI run, a pull request, a timer or another issue;
bd closerefuses until they resolve, unless--forceis given or the check cannot run (close). - Merging from Dolt. Field-level merges, branches, push and pull between machines, and hash IDs, so issues created on different machines don't collide.
- Integrations with Linear, Jira, GitHub, GitLab, Azure DevOps and Notion.
Where Workfile is stronger
- Plain files. Every record is a Markdown file a reviewer reads in the pull request, with no database beside the code.
- Claims scoped to paths, enforced after the claim. Another actor cannot move or release the card, and Claude Code asks before an edit inside its scope.
- A done gate on acceptance criteria, with a forced close keeping its reason.
- History and typed memory. Changelog fragments cut into releases; decisions, learnings, incidents and conventions that
workfile agents contexthands to the next agent. - One package for the CLI, the web UI, the HTTP API and the MCP server, and no usage data sent.
Which to choose
- Beads if many agents drain a large dependency graph, gates on CI and pull requests matter, and a database beside the code is acceptable.
- Workfile if the records should be plain files reviewed in pull requests, "done" must mean the criteria are checked, and nothing should be sent by default.