The Beads Revolution

This isn't a think-piece — it's a build story with a thesis attached. The thesis: the humble Markdown TODO list, the default way agents track their own work, is the wrong data structure, and it's quietly sabotaging every long-horizon task you hand a model.

The thesis: Markdown can't hold a plan

Agents are happy to generate elaborate plans. The problem is what happens next — the plan is prose, not data, so the model has to re-read and re-interpret it on every turn, and it rarely bothers to update it. Yegge's opening claim is blunt.

"Your agents simply cannot keep track of work using Markdown files."— The Beads Revolution

The cost isn't just aesthetic. Re-parsing a text plan on every step burns the exact budget you wanted spent on the actual problem.

"Markdown plans are text, not structured data, and need to be parsed and interpreted — This places a high cognitive load on the model, which steals GPU cycles from your actual problem."— The Beads Revolution, on why Markdown fails

What Beads actually is

Beads (the CLI is bd) is deliberately unglamorous infrastructure: one Go binary, installable in a line, that gives agents a real issue tracker with dependencies and a queryable work queue instead of a wall of checkboxes. The trick that makes it agent-native is that it hides no state your git history can't reconstruct.

"The great thing is, yes, it's got some funky caching that occasionally gets out of sync. But the actual database is a JSONL file that's checked into your git project."— The Beads Revolution

Because the source of truth is plain text under version control, corruption is never fatal — it's just a diff to be replayed.

"You never actually lose anything! You can have a corrupted database, and once you discover the corruption, your agents can go back through git history and reconstruct the entire clean database from scratch."— The Beads Revolution

"Self-healing" is a euphemism (and that's the point)

Yegge is refreshingly honest that a vibe-coded system built this fast breaks — a lot. His move is to reframe the breakage: because the agent can repair the state itself from git, the human's job during a corruption event is roughly nothing.

"Beads is self-healing. Or more precisely, Beads sometimes gets all screwed up and the AI has to fix it. But we call it 'self-healing' because your role is just to finish your pumpkin spice latte while the AI does the fixing."— The Beads Revolution

Built in six days, by vibe-coding

The build story is the proof of concept for the build story. Yegge didn't spec Beads and hand it to engineers — he talked it into existence with an agent, front to back, and the speed is the argument for why agent-native tooling is arriving faster than the discourse around it.

"I vibe-coded this whole project, from design, to implementation, to validation and testing, to publishing it, to building a community around it, all in six days."— The Beads Revolution

The workflow: you and the agent, deciding together

Crucially, Beads isn't full autopilot. A dependency-aware tracker surfaces what's ready to work on, then hands the human the steering wheel — file, close, update, or re-prioritize. The tracker does the bookkeeping so the collaboration can be about judgment.

"You and the agent figure out what to work on next together. Beads just makes it easy."— The Beads Revolution