Beads, the task tracker your AI uses

What Beads is, why it suits AI agents, and how to use it by talking to your AI.

Beads, the task tracker your AI uses

Beads is a small task tracker that lives next to our files, built so AI agents can read and write tasks quickly. You don't use it directly. Your AI does.

The old way: you open Asana, click "new task", fill in the fields, drag a card to the right column. The new way: you say "File these as tasks for the retreat: the venue has to be booked before the invites go out." The AI creates the tasks, links them, and shows you the list.

This guide is a companion to AI is the interface (How we use AI), which explains why the AI is now the interface and apps are storage. Beads is the tasks half of that storage. To get Beads installed, see Set up your computer (with AI) in the Tao onboarding guide. Some teams' tasks live in GitHub or Asana instead; the workflow says which.

 Most trackers                  Beads
 ─────────────                  ─────
     You                            You
      │  you click, you read         │  you talk; it shows you a view
      ▼                              ▼
 App screens                     Your AI
      │                              │  runs bd (fast, on your machine)
      ▼                              ▼
 Tasks (in the cloud)            Tasks (in the project folder)
                                     ┊
                                     ┊ you can look too: bd ready, bd show

What Beads is, and why it was built

Trackers in three lines. A task tracker is a shared list of things to do, so the work isn't kept in someone's head. Each task has a status: open, in progress or closed. Some tasks wait on others: this can't start until that is done.

That last idea is the one that matters most. If the tracker knows what waits on what, it can tell you what is ready: what you could start right now.

 ┌───────────────────────┐            ┌───────────────────────┐
 │ lip-x7k.1             │   blocks   │ lip-x7k.2             │
 │ Book venue            │ ─────────▶ │ Send invites          │
 │ in progress           │            │ waiting               │
 └───────────────────────┘            └───────────────────────┘

 "What's ready?"  →  Book venue   (Send invites waits until it's closed)

What it is. Beads was made by Steve Yegge and announced in October 2025 as "a coding agent memory system". It is open source, and its command is bd. The name comes from tasks "chained together like beads"; a single task is sometimes called a bead. It is widely used by people working with AI agents.

The problem it solves. AI agents forget everything between sessions: all they know is what's written down where they can read it. Before Beads, agents kept plans in Markdown files, which multiplied, went stale and contradicted each other, and work the agent noticed along the way got lost.

What it is not. Yegge is clear that Beads is not a planning tool or a full project-management system like Jira; it holds the work in hand now. That matches how we work: the plan itself (the reasoning, the decisions) lives in Markdown documents; Beads holds the tasks that come out of the plan.

Built for the AI. Each design choice is about what makes the AI's job easy:

  • It lives in the project folder and runs on your machine. The AI can check and update tasks constantly, quickly and cheaply, with no slow trips to a website.
  • "What's ready?" is one command, worked out from the dependencies, so the AI can tell what comes next by itself.
  • New work gets filed on the spot, linked to the task it came from, so nothing is lost and the AI doesn't lose its thread.
  • Every new session starts informed. Our repositories tell the AI to use Beads for tasks, so a fresh session can pick up where the last one left off.

Other trackers can be driven from AI too, through their APIs. Beads is built for it. The trade-off is that it has almost no screens for people. That's the point of the AI guide: the AI builds the views you need. (Others have built viewers, such as web boards and editor plugins, but we don't rely on them.)

How to use it: talk to your AI

You rarely type bd yourself. You say what you want, and the AI runs the commands and shows you the result.

A short example on the team retreat (the task IDs are illustrative):

You: What's ready on the retreat?

AI: Two tasks are ready. Book venue (lip-x7k.1) is Sylvie's and in progress. Draft agenda (lip-x7k.3) is unassigned. Send invites is waiting on the venue.

You: I'll take the agenda.

AI: Claimed lip-x7k.3, Draft agenda.

You: Oh, and the venue's booked: Hawkwood, 14 to 16 November. The cheaper place fell through, note that.

AI: Closed Book venue with that reason and added the note. Send invites is now ready.

You: We still don't know about dietary needs. File that.

AI: Created Collect dietary needs (lip-x7k.5), linked as found while booking the venue.

You: Show me what you changed in Beads this session.

AI: Four changes: claimed lip-x7k.3, closed lip-x7k.1 with a reason and a note, created lip-x7k.5.

Refer to tasks by their title and let the AI find the ID; dictation mangles IDs. Ask it to show the IDs when you want to check.

What's ready, what's stuck

"What's ready for me?" "What's blocked, and on whom?" "Show me the retreat work as a table by owner." The AI answers from Beads in seconds, in whatever form you ask for.

Filing a plan as tasks

Planning happens in conversation and in the plan document (see the AI guide). Once you agree the plan, say: "File these as tasks under the retreat. The venue blocks the invites." Then say "Show me the tree" and check the structure and the dependencies before you move on. A wrong dependency means a wrong answer to "what's ready?".

Updating as you go

One sentence each: "I'm starting the agenda." "Done; the reason is…" "Add a note: Sylvie prefers the Friday." "File a task for what we just found." This is what keeps the tracker true.

Landing the plane

The end-of-session routine is in the AI guide. The Beads part: close what's done, with a reason; add a note on where the next session should start; file follow-ups; and sync, so colleagues see your changes.

Handing over

A task someone else can pick up says what it's for, what "done" looks like, and what's been tried so far. A colleague or a fresh AI session can then start from it with "Show me lip-x7k.3". This is an example of good practice, not team policy; how much detail a handover needs is still an open question.

Asking about the past

"What did we close on content last week?" "Why does this task exist?" "What happened to the catering question?"

Phrases to copy

  • "What's ready for me today?"
  • "What's blocking the retreat, and who's it waiting on?"
  • "File these as tasks, and check for existing ones first."
  • "I'm starting the agenda."
  • "That's done. Close it and say why."
  • "File a task for that and link it to this one."
  • "Show me the tree for the retreat."
  • "Land the plane: close what's done, note where to start next, and sync."

Getting started: paste this into your AI

Once Beads is installed (computer setup), open a session in the repository and paste this:

I want to work with Beads, our task tracker, through you. Read guides/beads.md and docs/bd-task-conventions.md in this repository. Then pull the latest tasks, show me what's ready for me (my id is <your first name>), and from now on in this session: check for existing tasks before creating new ones, close tasks with a reason, file new work you discover as linked tasks, and when we finish, land the plane and sync. Show me what you changed in Beads before we stop.

What goes wrong, and how to check

  • Duplicates. The AI creates a task that already exists. Say "Check for an existing task before creating one."
  • Wrong or missing dependencies. "What's ready?" gives odd answers. Say "Show me the tree for the retreat."
  • Closed without evidence. Ask "What's the reason on that close?"
  • A colleague can't see your tasks. The changes weren't synced. Say "Sync Beads."
  • The AI won't close your task. Your Beads identity isn't set; see setting your identity.
  • The one check for any session: "Show me what you changed in Beads."

If you want to look yourself, a few commands are enough: bd ready, bd show <id>, bd list, and bd human, which prints the short list of commands meant for people. Or ask the AI for a view: a table, an HTML page, a graph.

Glossary

  • Task (also issue, or bead). One thing to do, with a status: open, in progress or closed.
  • Epic. A larger piece of work grouping several tasks, its children (IDs like lip-x7k.1).
  • Dependency, blocks. "A blocks B" means B can't start until A is closed.
  • Ready. Open, and not waiting on anything.
  • Claim. Mark a task as yours and in progress.
  • Note. Context added to a task as work goes on.
  • Priority. P0 (critical) to P4 (backlog).
  • Sync. Share your task changes with the team, and get theirs.

Sources

Edit this page

Links to this page:

  1. Our office: how Life Itself organises shared work
Built with LogoFlowershow