A coding agent can hold an astonishing amount of code in its head and still forget the job when the session ends. Beads fixes that. It keeps the decisions, discoveries, status, and next work in a durable graph that the next session can pick up without reconstructing the conversation.
Beads is the open protocol for durable agent work. bd is its default client, built for agents to call directly from the command line.
The work survives the worker
Most agent plans live in the worst possible place: inside the agent that is doing the work. A context compaction flattens the details. A closed terminal takes the plan with it. A handoff leaves the next agent searching through transcripts, Markdown files, git history, and half-written code for clues.
A bead is one durable unit of work. It has an ID, a status, a priority, a description, and history. It can be a bug, task, feature, epic, or another typed piece of work. The agent can create it when work is planned, update it while work changes, and close it when the result is done.
The important part is where that record lives. Beads stores work in Dolt, a version-controlled SQL database, outside the model’s context window. The session can disappear while the work remains queryable.
That changes a handoff from:
Read everything and guess where the previous agent stopped.
to:
Show me the in-progress bead, its notes, what blocks it, and what is ready next.
For the exact setup and first commands, use the Beads quick start. The rest of this page explains what durable work lets an agent do.
A graph, because real work is connected
A flat task list records that six things exist. It cannot reliably explain which two belong to the same feature, which task must finish before another can begin, or why a newly discovered bug appeared.
Beads connects work with typed relationships:
- Parent/child edges group a larger outcome with the work inside it.
- Blocking edges record hard execution order.
- Discovered-from edges preserve provenance when one task exposes another.
- Non-blocking dependency annotations such as
related,caused-by, andvalidatesadd context without changing readiness.
Duplicates and superseded work have a stronger lifecycle. bd duplicate and bd supersede add their own non-blocking typed edges, then close the obsolete bead. They are deliberate consolidation operations, rather than ordinary annotations attached with bd dep add.
From that graph, Beads computes the ready frontier: open work with no active blocker that is not already in progress, deferred, or waiting at a gate. An agent can ask bd ready instead of rereading the whole backlog and improvising a new plan.
Suppose a feature called “Add passkey login” has three child beads:
- Define the credential schema.
- Implement the login endpoint, blocked by the schema.
- Write the user guide, which can proceed in parallel.
While implementing the endpoint, the agent finds an unrelated session-expiry bug and records it as discovered from that work. The graph now carries both execution order and origin. When the schema closes, the endpoint enters the ready frontier automatically. Nobody has to rewrite the plan.
Why coding agents need a work graph walks through a complete example.
Built for agents to operate
An agent work system has to be usable by the agent. Beads gives agents structured CLI output, short collision-resistant hash IDs with database detection and retry, graph queries, and atomic claiming.
The working loop is deliberately small:
- Query ready work.
- Claim one bead.
- Record material discoveries and decisions as they happen.
- Close completed work.
- Let the updated graph reveal what is ready next.
The agent coordination guide covers the operational commands. Whatever command spelling the client uses, shared work state remains the source of truth.
Having an issue-tracker API does not make a task system agent-native. The system must survive sessions, express relationships, answer what is actionable, and accept safe updates from agents. Our category guide gives you a six-question test for evaluating one.
It survives compaction, restart, and handoff
Beads does not recover thoughts that were never written down, and it does not restore uncommitted code. It preserves the work state the agent chose to externalize: the job definition, status, notes, decisions, discovered work, and graph relationships.
That is enough to make common failures routine:
- After context compaction, the agent reloads the current workflow and project memory.
- After a terminal closes, a new session queries the same beads.
- After an agent crashes, a replacement sees the in-progress work and its dependencies.
- After a machine handoff, Dolt remotes can move the database to the next machine.
The practical discipline is simple: record the parts of the job another competent agent would need to continue. Beads gives those facts a stable home.
See durable memory for coding agents for the context-versus-work-state distinction, or agent crash recovery for the failure sequence.
Coding-agent recognition is observable
A clean-project response can show whether a named coding agent, model, and version recognizes the Beads name, the bd command, and the ready-claim-close loop without repository instructions. The result is a dated observation rather than a permanent property of every coding agent. The evaluation is reproducible because it records the environment, prompt, versions, and raw responses.
Project setup is the dependable layer. Beads ships first-party integration recipes for Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and other coding tools. The recipes install the instruction files, skill, rules, or hooks each host reads. bd prime then supplies the current workflow and project memory at session start and, where the host supports it, after compaction.
A correct clean-project response can shorten orientation. The installed integration tells the agent how this repository actually works.
Test coding-agent recognition of Beads separates clean-project behavior from initialized-project behavior and gives a reproducible evaluation.
Beads has crossed 800K downloads
The “#1” claim on this page uses a defined comparison: the July 2026 review of direct Beads forks and independent agent-work alternatives (br, ticket/tk, Trekker, Knots, and PaiR). Beads led that measured cohort by a wide margin on both GitHub stars and cumulative release-asset downloads. The comparison excludes adjacent PRD planners and human issue trackers, whose jobs and distribution channels differ; the agent work management roundup compares only the direct product set.
As of July 30, 2026, Beads had more than 800,000 cumulative downloads across its GitHub release assets. Downloads include upgrades, CI fetches, and retries; they are not a count of unique users. The npm package is an installation route that fetches the matching GitHub release binary, so npm downloads are not added again.
The result is a substantial public footprint plus a workflow developers can carry between coding tools. The work graph stays intact when the agent vendor changes.
Start alone; bring the team when the boundary changes
Open source Beads is the individual-developer product. It gives one developer and their agents durable work, local control, and the ability to move that work through Dolt remotes.
Team operation introduces a different set of needs: shared identity, policy, governance, multiple machines, and integration with organizational systems of record. That is the boundary for Beads Team Server, available in preview through design partnerships.
There are two adoption paths:
- Start with Beads for durable work, then add Beads Team Server when those beads need team sharing and governance.
- Start with Gas City for an individual software factory, then move the same factory configuration to Gasworks when multiple operators need to run it together. Gasworks includes Beads Team Server.
You do not have to adopt a factory platform to benefit from Beads. Start by giving one real piece of work a durable home.
If your agents already rely on Beads and the work now needs to cross team and governance boundaries, request a Beads Team Server design partnership.
Related articles
- Durable memory for coding agents: Separate model context from the work state another session needs.
- Why coding agents need a work graph: Explore hierarchy, blocking, provenance, and the ready frontier in one example.
- Recover agent work after a crash: Follow an interrupted bead through lease expiry, reclaim, and replacement.
- Test coding-agent recognition of Beads: Compare a clean-project observation with the official setup that makes project behavior repeatable.