Beads: issue tracking for agent work

Table of Contents

Why I looked at Beads

I have been using more AI-assisted coding tools lately, and one question keeps coming back: where does the work live?

A markdown TODO file starts nice and then becomes stale. GitHub issues are fine, but for small private projects I do not always want to do that either. Maybe I’m just not used to the gh CLI? (Happy to hear about your experiences)

This is one angle where Beads fits nicely.

Beads is a command line issue tracker. The command is bd. Its own help describes it as:

Issues chained together like beads. A lightweight issue tracker with first-class dependency support.

Beads is not trying to be Jira. It is trying to keep small pieces of work close to the code, visible to humans, and usable by coding agents. But meanwhile I would not use the word “lightweight” ;)

Beads overview (For beginners)

In practical terms, Beads gives you:

• issues stored inside the repository under .beads/
• a CLI-first workflow
• issue IDs like aholbreich-blog-tqi
• dependencies between issues
• ready-work detection, so an agent can ask “what is unblocked?”
• notes, comments, labels, priorities, and statuses
• Dolt-backed versioned storage for the issue database (Dolt is git DB!)
• commands that work well from scripts and agents.

The basic loop

The simplest Beads workflow is this:

bd ready
bd show <id>
bd update <id> --claim # Human or Coding Agent claims the work
# do the work
bd close <id>

That is the core idea.

bd ready is more useful than just listing open issues. It shows open work that has no active blockers. This matters when you have a few related tasks and you do not want an agent to start the last task before the first one is finished.

For example, if documentation depends on implementation, Beads can model that. The documentation issue can stay blocked until the implementation issue is closed.

Creating issues

For a quick issue:

bd create "Fix RSS feed for notes"

For a more explicit one:

bd create \
  --title "Add Field Notes section" \
  --description "Create an evergreen notes section outside the blog." \
  --type feature \
  --priority 2

For bigger work, I like an epic with child stories. Beads supports parent-child structure, so the project does not become a flat pile of tickets.

bd create --type epic --title "Create Field Notes section"
bd create --parent <epic-id> --type decision --title "Choose URL and taxonomy"
bd create --parent <epic-id> --type feature --title "Implement notes routing"

flowchart TD
    epic["🧵 Epic<br/>Create Field Notes section"]
    decision["🔀 Decision<br/>Choose URL and taxonomy"]
    feature["⚡ Feature<br/>Implement notes routing"]
    task["📋 Task<br/>Write redirect rules"]
    epic --> decision
    epic --> feature
    epic --> task

Dependencies

Dependencies are the reason Beads makes sense for agent work.

bd dep add <issue> <depends-on>

And a few more, to give you the idea:

bd dep tree <id>      # show the dependency tree
bd dep cycles         # detect circular dependencies
bd blocked            # show blocked issues
bd graph              # display dependency graph

This is much better than writing “do this after that” in a TODO comment and hoping somebody reads it.

Claiming work

When an agent starts an issue, it would typically claim it:

bd update <id> --claim

It becomes extremely useful in a multi-agent environment. This is theoretically the whole magic of Beads: it has the potential to coordinate agents at the level of individual tasks. To do so agents need to pass --actor, which in my experiments they don’t do reliably yet. So BEADS_AGENT_ACTOR is the more reliable alternative for now. I’m keeping notes on how I have done it so far. Maybe you have better ideas?

Anyway, update details anytime:

bd update <id> --priority 1
bd update <id> --add-label migration
bd update <id> --append-notes "Found one more legacy URL to preserve."

and close your task:

bd close <id>
# or with more context:
bd close <id> --reason "Implemented and build passed"

Final impression

I think Beads was early in the game and Steve Yegge built an excellent tool. I can personally stay on Beads for many of my tasks.

However I don’t like everything about Beads. Particularly:

• The AGENTS.md auto-creation. bd init creates or updates AGENTS.md by default, which I find quite invasive. It prescribes the agent to commit and push always — in Caps Lock ;)

• Beads is no longer the small tool it once was. Today, Beads is Dolt-first. Dolt is the source of truth, every write is auto-committed into Dolt history, sync happens via bd dolt push and bd dolt pull, and for multi-writer setups there is a full dolt sql-server mode. Git branches and Dolt branches are now decoupled. For a solo user like me, this feels a bit overkill.

• The opinionation runs deep, especially in Gas Town. Gas Town is an agent orchestration framework: tmux sessions, background daemons, worktree-based agent identities — you name it. Steve Yegge himself describes it as hands-on and expensive to operate. If Beads already feels heavy, Gas Town is the extreme end of that spectrum.

None of this makes Beads a bad tool. The core idea — structured work items, dependency-aware ready queues, claim/release primitives — is genuinely strong. But if what I want is a small, transparent, git-native task tracker for one to three agents, Beads today may already be more than I signed up for.

Several tools were born explicitly from dissatisfaction with Beads’ weight. wedow/ticket, git-friendly, zero daemons. Beans takes a middle path with local SQLite. Trekker goes fully local with a dashboard. When multiple independent projects emerge to solve the same problem with less machinery, that is a signal.

So I keep exploring.

What’s your preferred tool for the task?