(2025-10-15) Yegge The Beads Revolution How I Built The Todo System That Ai Agents Actually Want To Use

Steve Yegge: The Beads Revolution: How I Built The TODO System That AI Agents Actually Want to Use.

From Idea to a Thousand GitHub Stars in Six Days

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. (It was based on a TypeScript library I’d created, so I had a head start, but that version was also less than a week old.)

Beads is starting to gain converts. In particular, the AIs love it. Go ahead, ask them. Point your favorite coding agent at my GitHub repo and ask them, would this be useful?

Beads elegantly solves a core problem that Matt Beane had been struggling with — one that we’ve all been struggling with — namely, managing hierarchical TODOs and project planning over long-horizon, multi-session workflows.

Community Response

It may have been created quickly, but the core idea was based on a year of hard time with agentic workflows using plans and TODO lists. So when I stumbled on this solution, I knew within the space of a day that it felt right, and that I’d had a genuine breakthrough.

The Core Problem: Markdown Plans Don’t Work

Your agents simply cannot keep track of work using Markdown files.

Markdown plans are text, not structured data, and need to be parsed and interpreted — This places a high cognitive load on the model,.. They’re not queryable, which means it’s extremely hard to build a work queue from markdown plans

Agents rarely update the plans as they work, so the plans bit-rot very fast

Beads is The Whole Package

Unlike Jira and GitHub issues, Beads can create epics with child issues, which in turn can be child issues, so you can model arbitrarily complicated project plans and work graphs.

Issues in Beads have four different kinds of dependency links, including provenance

In the picture above you can see how a typical agent interaction goes when using Beads. Issue numbers are scattered through the conversation. You always know what work is blocking, what work is ready, what’s high priority. You and the agent can both reason about giant plans this way.

Notice also in the conversation, it’s giving me options to file issues, close issues, or update issues. Working with Beads is interactive. You and the agent figure out what to work on next together.

Beads Heals Itself

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.
Which means — you never actually lose anything!

This is what enables Beads to have such a lightweight, high-performance, and pragmatic design, compared to something like git-bug or Radicle, both of which — at least according to Claude — are too heavyweight for fast agentic workflow loops.

TODO: Drop TODOs

It’s only a matter of time before you realize Beads is The Way. I know a bunch of you have been chasing the hierarchical markdown-plan dream. If you have reached the point where you have started to think about maybe moving the plans into a wiki, you have officially felt the pain that Beads completely solves.
Hell, if you want Beads to act like a wiki, it’ll act like a wiki.

Seriously, do yourself a favor. Fire up any agent — Claude Code...
Go ask your agentic assistant if it wants to use Beads. See what it says.
And then, once it has convinced you to use it, have it set Beads up! It can do all the investigation and the heavy lifting for you.

from then on, use an issues-first workflow