Beads Best Practices

Six weeks after launch, Steve wrote up how to actually operate Beads, and the rules describe software with no ancestor in the issue-tracker family tree: keep the live database under roughly 500 issues, because agents grep the raw JSONL and choke past 25k tokens; set bd cleanup to delete anything older than two days, since git history keeps the bodies; restart the agent constantly and let the tracker be the memory that survives it. Read closely, the maintenance advice doubles as a defect log — upgrade weekly because merges still break, expect to ask the agent to mop up "Beads messes." Steve knows, and says so with a candor most tool authors can't afford: Beads is "a crummy architecture (by pre-AI standards)" that works because AI hydrates it, patching around the edge cases faster than the edges can cut anyone.

The best material is the middle stretch, where Jeffrey Emanuel, the man quoted above, turns out to run his agents the opposite of how Steve does: all of them loose in one shared folder, coordinating through a file-reservation scheme that reminds Steve of sneakernet version control at Accenture in the late 90s, when he once promised a colleague he'd release a locked file in "about a month." Steve thinks the setup is nuts, likens the agents to "raccoons in a dumpster," and concedes they sort it out anyway. Then the two meet in person and walk two hours through Manhattan rain, repeatedly marching twenty minutes the wrong way, until Steve learns something about his companion that reframes the whole afternoon. The essay plays that discovery as a jump-scare, and it works best if nothing here tips it.