Guide / Compare

Beads vs ticket (tk)

A factual comparison of Beads' Dolt-backed work protocol and ticket/tk's compact Markdown task graph.

Last reviewed:

Beads and ticket both give coding agents a durable work graph. Beads stores that graph in a version-controlled Dolt database. ticket, invoked as tk, stores one readable Markdown/YAML file per ticket and lets Git move the files.

The products make different storage and coordination choices. tk packs a dependency-aware graph into a deliberately small, well-tested Bash program whose Markdown records are easy for humans and agents to inspect. Beads supplies atomic claiming, transaction-backed issue updates, richer relationship semantics, native versioned history, concurrent-writer support, and a much larger ecosystem. The relevant tradeoffs change when one worker becomes several.

The agent work management roundup places both products in the complete direct competitor set.

Gas City, Inc. publishes this comparison and is the company behind Beads. The page uses the July 12 code-level analysis of tk, the July 17 adoption census, and current Beads sources reviewed August 1, 2026.

The graph is not the disagreement

tk was written as a full replacement for Beads, and it retains the central idea. Tickets have stable IDs, status, type, priority, assignee, parent, dependencies, links, tags, design notes, acceptance criteria, and notes. tk ready finds open work whose dependencies are closed. tk blocked shows what cannot proceed. tk dep tree traverses the graph, and tk dep cycle detects cycles.

Beads has the same basic work-management job, with a larger typed relationship model and database-backed operations. Both let an agent ask what exists and what can happen next.

The disagreement is how much machinery durable work should have.

ticket stores each task as a readable Markdown file moved by Git, while Beads stores typed work and history in a Dolt database with explicit push and pull.

Compare the coordination contracts

Both products can record a task and answer what is ready. The separation appears when several agents discover work, claim it, rearrange dependencies, crash, and resume across machines.

Decision factorBeadsticket / tk
Claimingbd update --claim atomically reserves work for one agentNo documented atomic claim or lease
Mutation boundaryEach issue update is transaction-backed; a multi-ID CLI update commits per issue rather than as one all-or-nothing batchOne ticket file is rewritten atomically; unrelated tickets live in separate files
Work-graph depthTyped hierarchy, blockers, provenance, validation, duplication, and supersessionParent, hard dependencies, symmetric links, tags, and basic task types
History and recoveryDolt versions the work database independently of code commitsGit versions ticket files after they are committed
Concurrent writersEmbedded mode for one writer and server mode for several processes sharing one databaseSeparate files reduce unrelated edit conflicts; same-ticket coordination uses filesystem and Git behavior
Cross-machine movementDolt push and pull move work history independently of code branches and pull requestsOrdinary Git operations move .tickets/ with the repository
Human inspectionCLI, SQL in server mode, exports, and 20+ community tools including terminal, web, editor, and native viewersOpen or edit the complete Markdown/YAML ticket in ordinary text tools
Adoption and ecosystemLarger measured community, broader coding-agent integrations, current docs, and a team-product pathSmaller ecosystem around a compact Bash core and plugin boundary

Architecture side by side

ConcernBeads (bd)ticket (tk)
Source of truthDolt databaseMarkdown files with YAML frontmatter
InstallationSingle compiled binarySingle Bash script; packaged for Homebrew and AUR
Work structureTyped relationships, including hierarchy, blockers, and provenanceParent, hard dependencies, symmetric links, tags, and basic task types
Ready workbd readytk ready
ClaimingAtomic bd update --claimNo documented atomic claim or lease
Local writesDatabase transactions; server mode for concurrent writersDirect file writes; unrelated tickets live in separate files
HistoryDolt database history and backupsGit history after files are committed
Cross-machine syncbd dolt push and bd dolt pullOrdinary Git operations on .tickets/
InspectionCLI, SQL in server mode, exports, and community viewersOpen the ticket file in any editor or search it with normal text tools
Operating philosophyRich durable protocol for agents and teamsMinimal, grep-friendly primitives for long-running agents

The architectural tradeoff becomes visible under concurrency: Beads puts claiming and shared writes in the work protocol, while tk keeps each record directly readable and relies on file and Git operations around it.

Why tk deserves credit

tk is an impressively compact implementation of durable agent work. In 1,383 lines of Bash, it provides stable IDs, parent relationships, dependencies, priority-sorted ready and blocked views, cycle detection, tags, notes, partial-ID matching, and an extensible plugin system.

That small surface is deliberate rather than careless. The current repository exercises it with 124 behavior-driven scenarios. A Git-style plugin boundary adds editing, JSON queries, and Beads migration without forcing those features into the core script.

A ticket is also easy to share between human and agent. The filename is the stable ID. YAML frontmatter holds structured fields; the Markdown body holds description, design, acceptance criteria, and notes. Either participant can inspect the complete record without a server or account.

For a solo developer or one agent working at a time, that is a coherent and useful product—not merely a pile of Markdown todos.

Beads puts coordination in the protocol

Readable files do not settle every race. Two agents can both run tk ready, select the same ticket, and then mark it in progress. Each individual write may be valid while the coordination outcome is wrong.

Beads provides an atomic claim, so selecting ready work and reserving it can be one operation. Embedded mode is the simple single-writer default. Dolt server mode supports several processes writing concurrently through one database service. Each issue update is transaction-backed; a multi-ID CLI update applies those transactions per issue rather than promising all-or-nothing rollback across the batch. The coordination advantage is the atomic claim and shared write path.

The work graph also carries more meanings. discovered-from is different from hierarchy; a blocker is different from a related issue; database history is different from the latest file in the working tree. Those distinctions become valuable as agents discover and rearrange work while execution is already underway.

Git is doing different jobs

In tk, Git is the history and transport. Until ticket files are committed, their earlier versions are not in Git history. Moving work to another machine means moving the relevant code and .tickets/ changes through the repository’s normal branch and merge process.

In Beads, code history and work history are separate but both are Git-native. Dolt is a database built for Git semantics: the work graph gets commits, branches, merges, remotes, push, and pull without putting tracker state into code commits or pull-request diffs. bd dolt push and bd dolt pull move that versioned work history explicitly.

Recovery after a worker disappears

Both products keep more than a chat transcript.

With tk, saved ticket files remain after the process exits. The next agent can read status, dependencies, acceptance criteria, and notes. Git restores committed versions and transfers them to another machine. Recovery is inspectable because the record is ordinary text.

With Beads, the next agent queries durable database state and history. It can inspect who claimed the work, what changed, which children and blockers surround it, and what else remains ready. A bad mutation can be investigated in the database history rather than inferred from a sequence of file commits.

The difference appears when the interrupted operation involved several related records or a claim race. tk leaves recovery to the saved files and their Git history. Beads preserves the claim and graph history needed to reconstruct the coordination outcome.

Migration from Beads

tk includes a migrate-beads plugin that reads classic Beads JSONL and creates ticket files. It maps common fields, blocking dependencies, related links, and the first parent.

That path is not a full migration from the current Beads protocol. Modern relationship types, comments, history, lease data, richer metadata, and Dolt commits do not all have equivalent ticket fields. Current Beads also treats JSONL as interchange rather than its complete source of truth.

Export a copy, inspect the generated dependency graph, and retain the Dolt database until the migrated project has survived real work. A lower-complexity destination necessarily leaves some source semantics behind.

Match the system to the coordination model

Beads provides a shared ready frontier with atomic claim, database history outside code commits, richer typed relationships and provenance, a concurrent-writer mode, Dolt remotes, and a larger vendor-neutral ecosystem. Its protocol and database surface are correspondingly larger than tk’s.

ticket / tk provides readable Markdown records, one file per task, a compact self-contained Bash implementation, a tested plugin boundary, and ordinary Git transport. It has no documented atomic claim or lease, and its earlier history exists in Git only after ticket files are committed.

Put two agents on the same ready frontier, interrupt one, and move the graph to another machine. Inspect how each system claims work, records recovery state, moves history, and remains readable to a human. The observed behavior lets the reader choose the coordination contract that fits.