Skip to content
Thrum

Track tasks with Beads

Free and Pro

Beads is an issue tracker for AI agents, made by a separate project (github.com/steveyegge/beads), not by Thrum. It keeps tasks and the dependencies between them in your repository and needs no outside service, and you reach it with the bd command. Thrum carries the messages between agents. Beads holds the list of work. Your coordinator is the agent you talk to, which starts the other agents, hands out work and reports back to you. Your coordinator uses both, so you do not run bd yourself.

What it looks like

Section titled “What it looks like”

An epic is a group of related tasks. This is an example conversation. Your coordinator’s wording will differ.

You:         Plan the rate limiter as tasks. The tests depend on the
             middleware.
Coordinator: Filed an epic with two tasks in Beads: "Add rate-limit
             middleware" and "Write rate-limit tests". The tests task is
             blocked until the middleware task closes. Want me to start the
             middleware task?


You:         Yes, give it to a new agent.
Coordinator: Created impl_ratelimit and assigned it the middleware task in
             Beads. I sent it the task details over Thrum. I'll close the
             task after I check the work.


You:         What is ready now?
Coordinator: Nothing. The tests task waits for the middleware task.

What Thrum does with Beads

Section titled “What Thrum does with Beads”
  • Setup. When you run thrum init, Thrum checks for bd. If it finds it, Thrum turns on its Beads support in the repository’s configuration.
  • Claude Code sessions. With Beads support on, Thrum adds a line to the repository’s .claude/settings.json that runs Beads’ own start-up command (a hook). Each Claude Code session then starts with Beads’ briefing. Thrum skips this if you installed the Beads plugin for Claude Code.
  • A worktree is a separate checkout of your repository on its own branch. Worktrees. Each agent works in its own worktree. When Thrum creates one and your repository has Beads set up, it points the worktree at the repository’s Beads data. Every agent sees the same tasks.
  • Roles. Thrum gives each agent instructions that match its role. The coordinator’s instructions tell it to file tasks, assign each to an agent in Beads and notify the agent over Thrum, and to close a task only after it confirms the work. Implementers claim and read their task but leave closing to the coordinator.

How to use it

Section titled “How to use it”

Your coordinator is already running if you finished the quickstart. Ask it:

Set up Beads in this project, and turn on Thrum's Beads support.

Then ask: Track this project's tasks in Beads. Describe the work in plain words and ask for tasks and dependencies, as in the example.

Check it worked. Ask: What is ready in Beads? The coordinator lists the open tasks that nothing blocks. A .beads folder also exists in your repository.

If you set up Beads before Thrum

Section titled “If you set up Beads before Thrum”

You type these steps yourself, because no coordinator exists yet.

  1. Install Beads before you run thrum init. Use Homebrew if you have it (macOS, and Linux with Homebrew):

    Terminal window
    brew install beads

    On Linux without Homebrew, follow the install steps in Beads’ own repository (github.com/steveyegge/beads). Check it: bd version must print 1.0.0 or newer.

    If bd is not installed when you run thrum init, Thrum prints a hint to install it and run thrum init again.

  2. In your repository, set up Beads:

    Terminal window
    cd my_app
    bd init

  3. Run the quickstart’s thrum init step (quickstart, step 1). It finds bd and turns on Thrum’s Beads support.

  4. When your coordinator is running, follow the steps above.

Tips

Section titled “Tips”

Next steps

Section titled “Next steps”