Beads for agents

Over the last week, I've been using beads heavily as a part of my Claude code workflow.

Why beads over Markdown?

I have many things to say about beads, but the order in unclear. But on the twitter/X discourse, I have noticed that this is a common question people have: "How is this different from just putting plans in a features/plan.md?".

So here, I would like to address it first, before I share more thoughts on beads in the future.

Say I get an agent to write a plan to a markdown file (they love to do it).

After a while, I check in: "Hey, what's up with that markdown file, can you check it?", and (usually, for long tasks), the agent has done a) more, b) less, or c) something else entirely vs what was specified in the original markdown.

Markdown just doesn't work for agents.

The agents reads a .md, finds where in the file is relevant (context-heavy, slow lookup), adds more things (token-heavy writes). To keep things in sync, it may to update multiple locations. It's not just wasted time, but also tokens & precious context.

Now, imagine if there was a system which could make this tedious work just go away. *swoosh*

That is beads.

In my view, beads is a sane task tracker for your code agents, which lets them do things efficiently and without forgetting. At the same time, it's also a place to think with the agents, to collaborate on issues and find connections between things. It makes the agent to-dos visible to humans & trackable/maintainable across sessions.

If I was just a dev doing a single task, I would use a simple to-do list for that. (For eg, I think interleaved scratchpads are fascinating, and I'm going to explore them).

But beads lets you make epics & features, connected sub-tasks. Everything has a description, and the tool reminds the agent to fill it.

It's making your agent more grounded & capable, focused on tasks and able to look at the depth of connections between them. I can definitely recommend just trying it out yourself and seeing how it fits into, or changes your workflow.

The issues with Markdown

• Slow, tedious reads/writes
• Inability of agents to keep track of what was followed
• Looks good to humans, not good for machine use

What beads did

• added a tracking board
• added simple way to keep it collaborative
• made sure it updates by providing instructions in claude.md/agents.md

What beads can improve

• multi-repo collab (they have it, more below)
• my own planning tasks vs global planning and ability to manage them (not OSS contributor mode, but more like collab with PMs in a team?). This direction is very interesting to me as it potentially lets me direct features end-to-end.

Beyond beads?

I wonder what a collaboration tool for agents would look like, where multi repo agents can collab with a product director, someone who controls the direction of the product and understands how to drive the right output.

Such a director would also need many other tools, and this is a direction I plan to explore further in my articles.

I also wonder what a thinking pool for an agent would look like, where it could think and reason issues across multiple services which could be fixed, Like a full stack staff engineer would, when tasked with a thing to do across a large org with multiple repos for example.

When I dived in, I found that beads has some initial support building up for multi-repo use cases, but I still think it takes a conversation to set contracts. There is something very interesting here to build.

I imagine a supervisor dev which looks over many domains, which can collaborate with specialized agents across micro-srervices/repos. This seems to be a very complex issue in many orgs (including some I see up close), and does have a lot of interesting, hidden problems to solve.

Exciting times!