First, what is beads?
If you've run engineering at scale and doubt agents can, start your inspection here — this is the substrate every other claim on this site rests on.
Beads (bd) is a lightweight, git-embedded issue tracker with first-class dependency support — "issues chained together like beads." Each issue (a bead) is a structured record — type, status, priority, labels, typed dependency edges, gates, comments, notes — stored in a versioned SQL database (Dolt) thatbd serves locally, one shared server per host, started for you, and distributed through git itself. There is no web app to log into and no hosted service: the entire tracker is a local CLI, which is exactly what makes it the right substrate for agents.
Why it's more efficient for agents than a hosted tracker
An agent's scarcest resources are context tokens and round-trips. A hosted tracker spends both: auth handshakes, paginated API payloads, HTML noise, rate limits. Beads answers in one local, zero-latency command with compact structured output:
- One command, machine-shaped.
bd ready --jsonreturns the actionable frontier as data — no scraping, no pagination, no prose to parse. Every read and write is a single cheap CLI call an agent can't fumble. - Context recovery is one call.
bd primere-hydrates full project state after compaction or a fresh session — the antidote to agent amnesia. - Coordination primitives built in. Atomic claims, gates, merge-slots, and a per-actor audit trail are tracker features, not conventions an agent must remember to follow.
- Duplicates surface, not bury.
bd find-duplicatesruns when a report lands and again at triage, so a colliding request never buries the queue. (Beads also ships a memory store; a hive keeps beads issues only and denies it — knowledge belongs in the project's own records.)
The work-graph: one DAG across every repo and product
Because dependencies are typed edges (blocks, related,parent-child, discovered-from, among others), the backlog isn't a list — it's a traversable graph. Epics group beads into molecules; a workstream is just an epic whose children are epics — which is how a whole product is represented with no new machinery. Every repo is a hive, HQ aggregates them, and cross-hive references link their graphs — so a blocking feature in one repo visibly blocks work in another, andbd ready / bd blocked compute the frontier and the bottlenecks across the entire portfolio at once.
Bi-directional sync: humans keep their boards
Beads ships sync integrations for GitHub Issues, GitLab, Jira, Linear, and Azure DevOps — bd github sync / push / pull and friends — so the graph mirrors into the trackers humans already visualize with. A PM triages in Jira or drags cards on a GitHub board; the changes pull back into beads;external_ref preserves provenance in both directions, and JSONL interchange covers export, migration, and viewers. The division of labor falls out naturally:agents traverse the graph, humans watch the boards — one source of truth, two native interfaces.
web-4 is blocked byapi-9 in a different repo — an edge no per-repo board can show, but onebd blocked surfaces instantly — and the workstream rolls it all up into a product view. Meanwhile the same beads mirror into GitHub/Jira/Linear so humans plan and visualize where they already live.bd ready --json # the unblocked frontier, machine-readable
bd dep add web-4 api-9 # web-4 is blocked by api-9 — a cross-hive edge
bd graph api-9 # who is waiting on this bead?
bd github sync # mirror to / from the humans' boardWhy beads is the right substrate for agents
These are the opinions the whole design leans on — why a dependency-linked, git-native issue database beats markdown TODOs, chat scrollback, or a hosted tracker when the workers are LLM agents:
⬢Agents forget; beads don't
Context windows compact, sessions die, threads reset. Beads is the durable shared memory that survives all of it: any agent runs bd prime and recovers the full project state. Work that must outlive a session goes in a bead, never a scratch file — once a plan is filed, beads is the source of truth and the spec that produced it is absorbed scaffolding.
⬢"What next?" is computable
Issues form a dependency DAG, so bd ready mechanically yields the unblocked frontier. An agent never has to infer priorities from prose — the tracker answers the single question agents ask most, and answers it across every repo viabh hq bd ready.
⬢Atomic claims, many workers
bd update --claim is an atomic take. Parallel developers can't collide on a bead, and every claim/assign is stamped with a per-agent actor (bd --actor) so the audit trail says exactly who did what.
⬢Git-native, serverless
Issue history rides refs/dolt/data on the repo's own remote. Nothing hosted, nothing to pay for, nothing to be down: a fresh clone plusbd bootstrap is a fully hydrated tracker. Backup rides wherever the repo is mirrored. Distribution to a fleet of agents is just git.
⬢Gates are machine-readable state
Human checkpoints — plan approval, kickoff, review, security — arebd gate records, not vibes in a chat thread. The merge path refuses to land while any gate naming the bead is open. Agents can see, open, and wait on gates; only the right seat can resolve them.
⬢Discovered work becomes durable work
Implementation always uncovers follow-ups. With beads, the reflex isbd create + a dependency link — the discovery enters the same DAG the next agent will pull from, instead of dying in a session summary.