I am a semi-chaotic software engineer. I like to keep a bit of a pathfinder's spirit: start moving, learn what is actually there, and fix things along the way. When I am working alone in a codebase, that can work surprisingly well. Once several coding agents are working at the same time, it gets harder to tell whether we are all heading in the same direction.
I catch myself asking the same questions: What was that agent doing? What is blocked? What is the most important thing to fix next? My usual response was to ask an agent for a fresh status update. That works, but it also spends time and tokens reconstructing a picture of the project that I had already built once.
Before Beads, I mostly asked the agent to make a plan itself. It would tell me "this will take you 2-3 weeks" and then proceed to one-shot the whole thing. I also had to give explicit instructions, and sometimes it still didn't update the docs or the progress.
Software teams solved this with issue trackers a long time ago, and Beads is that idea built for coding agents. I came across it through Steve Yegge's posts and podcast appearances. What it gave me is a way to orchestrate work across multiple chats, keep the order of the work straight, and stop depending on one agent that loses its context the day after.
What is Beads?
Beads is a command-line issue tracker for coding agents. Its command is bd. Instead of keeping a loose to-do list in a chat or a Markdown file, you create issues that can have descriptions, priorities, statuses, and relationships to other issues. Those issues persist beyond one agent conversation, so a new session can pick up the work without relying on the previous session's memory.
The useful part is the dependency graph. Suppose a feature needs a database change before the API can be updated. You record that relationship, and bd ready shows the work that has no open blockers. An agent can look at an issue, claim it, work on it, and close it. Closing a blocker makes the next task ready. The project README has the full command reference and setup.
The plan becomes part of the project workflow, instead of something I keep asking an agent to summarize.
How to start using it
You don't need a swarm of agents to get value from Beads. I installed bd, ran bd init in a project, and asked Claude to use it. Sometimes I only ran bd init and told it to use bd prime for more context.
brew install beads
cd your-project
bd init
bd init also creates or updates an AGENTS.md, so agents can find the workflow when they enter the repo. Read what it wrote and adapt it to how you want your agents to work. From there the agent runs the loop itself: bd ready to find work, bd show <id> for the details, bd update <id> --claim to take it, bd close <id> when it is done.
Here is bd ready in my Racing event tracker project, trimmed to a few rows:
$ bd ready
○ Racing_event_tracker-lj6m P1 [epic] Feeder series (F2/F3): correct calendars + session times, and guard against template rot
○ Racing_event_tracker-fwke P2 Waza follow-up: contain copilot-sdk executor + move file-shaped assertions to file/diff graders
○ Racing_event_tracker-jwt3 P2 [epic] Kiosk v2 — calm the motion, add personality
○ Racing_event_tracker-pze4 P2 [epic] Waza next plan — Track A (local, mock-only)
○ Racing_event_tracker-xdx8 P2 [bug] Stale past events linger in gold/upcoming.json
Each row is a task with no open blockers: the ID, the priority, the type in brackets when it has one, and the title.
The first real win was a bug in the data pipeline, a lingering issue. I never asked the agent to go looking for it. It spotted the problem on its own and logged an issue with the details. Beads didn't find the bug. The agent did, and Beads gave it somewhere to put it. It’s a small change, and a good place to start: let the agent file the issue instead of leaving it buried in the chat.
For bigger tasks I use a planner, or a divide-and-conquer approach. It pays off most when pieces can be picked up in parallel and I have agents to spare, either tokens or request limits. A typical plan came out at about 4 epics, depending on what I was working on, with a clear division of work between them. Sequential is the default, but subagents are where it scales. An orchestrating agent can use bd ready to hand independent tasks to subagents, and each one claims its own task with bd update <id> --claim.
What went wrong most often was issues that never got closed. The acceptance criteria included committing or asking me for a last check, the agent couldn't complete that, and the issue stayed open. I then had to close it myself or ask the agent to close it again.
The dashboard I wanted
The command line is useful for agents, but I wanted a faster way to see the whole project myself. So I built a local web dashboard for my Beads issues. It lets me scan the work, see the visual progress of subagents, add comments, and remove issues that no longer matter.
The main view is a kanban board with open, in progress and closed columns. There is also a hierarchical view, where I can edit things and watch the agents pick up work live and move it along.
I built it with Claude, in a fork of Beads, in one shot. I just told it: "build me a local dashboard so that I can view progress."
My dashboard on the Racing event tracker project: everything open, in progress and closed at a glance, updating live as the agents work.
It feels a little like project managing a team through a glorified Jira board that I built for myself. The difference is the speed: I can look at the board, spot a blocker or a questionable task, make a change, and send the agents back to work. Is this what project management feels like when the team moves this fast?
I couldn't find an existing dashboard at first. After building mine, I found the Beads community tools list and a GitHub discussion about Beads UIs. I was far from the only person who wanted a visual layer. One that looks really good to me is Beads Dashboard. It has an overview of ready, blocked and overdue work, a roadmap, and a drag-and-drop board, which is almost exactly what mine does, but as a ready-to-go VS Code extension.
So when do you build a small tool for yourself, and when do you use one that already exists? Rebuilding the same thing in several places can look wasteful from a software engineering perspective. But it took one prompt, and building it taught me more about Beads itself. For a personal tool, that was a fine trade.
The human in the loop
I used to ask an agent for a status update every time I lost the thread. Now I open the board, see what is in progress and what is stuck, and send the agents back to work. I still explore and change direction as I go, but now I do it with a map made specifically for agents, with me, the human, in the loop. Or really more of an observing human. And the question remains: how much more is there for me to observe in this abstraction layer?
This is only the start. Next, I want to explore what else Beads and agents can bring to the way I build.* *Feedback is welcome, and I'd love to hear about your own experience with Beads and agents.
References
Beads
-
Beads on GitHub, the
bdissue tracker for coding agents - Beads documentation
- Community tools list
- GitHub discussion about Beads UIs
My projects
- My Beads fork with the dashboard
- Racing event tracker, the project where I use Beads the most
Co-written with Claude and Codex. The structure, the opening and the experience behind every story are mine. They helped fill in the gaps, tighten the sentences and check the commands against the docs.
Top comments (0)