AI ERA2025

Beads Best Practices

Steve Yegge · Nov 24, 2025 · Medium

TL;DR — Beads is Yegge's git-native issue tracker that acts as shared memory for coding agents. This post is the field manual for using it well: plan outside Beads then import, get the AI to file lots of small issues, restart agents often, and — the part everyone underrates — keep the database small and do daily hygiene (bd doctor, bd cleanup, bd upgrade). A big, stale issue set silently degrades agent performance.

This isn't a manifesto — it's a maintenance guide. Yegge assumes you already believe in giving agents a memory that outlives a single session; the essay is about the unglamorous habits that keep that memory fast, clean, and trustworthy over weeks of use.

What Beads is for

Beads is the persistence layer for a swarm of coding agents. Where a single chat forgets everything at the end of the session, Beads is a git-native issue tracker the agents read and write directly — so plans, dependencies, and discovered work survive restarts. Paired with a messaging layer, that's the whole recipe for multi-agent work.

"He said that Beads gives the agents shared memory, and MCP Agent Mail gives them messaging… and that's all they need."— Beads Best Practices

A recurring anxiety with any delete-based cleanup is losing work. Yegge defuses it up front: nothing is ever truly gone, because the tracker lives inside version control.

"The issues are always in git history, even after deleting them, because Beads is a git-native issue tracker."— Beads Best Practices

The workflow: plan outside, then import

Yegge's strongest process recommendation is to not do your big-picture planning inside Beads. Design the plan somewhere built for planning — he uses tools like OpenSpec — iterate on it hard, and only then import the result as epics and issues wired up with dependencies and parallelization in mind.

Plan externally, then import. Refine the plan up to ~5 times, then refine the resulting Beads epics up to ~5 more times before you decide you can't do much better.
Let the agent file the issues. Ask the AI to break work down and file beads for anything longer than a couple of minutes — including as the actionable output of a code review.
Restart agents frequently. One task per session is cheaper and performs better than a long-running context; Beads is what makes the restart lossless.

File lots of issues

The system only works if there's something in it. Yegge wants the issue tracker to be the agent's reflex for capturing work — and reports the models mostly do this on their own, with an occasional nudge.

"The models will often choose to file Beads issues spontaneously, but nudging it occasionally will help as well."— Beads Best Practices

The daily hygiene — and keeping it small

This is the section most people skip and later regret. Beads gets slow and noisy if you let it sprawl, so Yegge treats upkeep as a daily ritual, not an occasional cleanup.

Run bd doctor daily on your repos; run it with --fix periodically.
Upgrade often — bd upgrade at least every week or two, since the tool moves fast.
Cleanup on a cadence. Start thinking about it around 200 issues and rarely let the count exceed 500; bd cleanup then deletes old issues (git keeps them), and bd sync pushes the tidy state.
Use a short issue prefix (bd-, vc-, gt-) so IDs stay legible in agent output.

"You should get into the habit of running bd doctor every day on your repos."— Beads Best Practices

The reason to bother isn't tidiness for its own sake — it's throughput. A bloated working set is a tax the agents pay on every read.

"Keeping your working issue set small is a performance optimization that you will come to appreciate."— Beads Best Practices

Why the "crummy" architecture works

Yegge is cheerfully candid that Beads would look like a bad design to a pre-AI engineer — it leans on the agent to paper over its own rough edges. That's not an accident; it's the bet. The tool is built for a world where an AI is always in the loop to smooth things over.

"It's a crummy architecture (by pre-AI standards) that requires AI in order to work around all its edge cases where it breaks."— Beads Best Practices

Which is exactly why the best practices are what they are: if the agent is the thing keeping the system honest, your job is to keep the agent fast (restart often, small database), keep it fed (file lots of issues), and keep it healthy (daily bd doctor). Do that, and Beads becomes the durable memory that lets a fleet of short-lived agents behave like one team with a long attention span.

Source note: quotes are verbatim from the Medium post and link back to it; the summary and section framing are ours. Beads itself lives at github.com/steveyegge/beads — check the current bd command surface there before relying on any flag above.