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) inside the repo and distributed through git itself. There is no web app to log into and no hosted service to run: the entire tracker is a local CLI, which is exactly what makes it the right substrate for agents.
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:
bd ready --json returns 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.bd prime re-hydrates full project state after compaction or a fresh session — the antidote to agent amnesia.bd remember / bd memoriespersist insights next to the work, so learning survives the session that produced it.Because dependencies are typed edges (blocks, related,parent-child, discovered-from), 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.
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' boardThese 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:
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 — markdown TODOs as source of truth are explicitly prohibited.
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.
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.
Issue history rides refs/dolt/data on the repo's own remote. Nothing to provision, 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.
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.
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.