| name | using-beads |
| description | Use at the start of and throughout ANY git-hosted work — tracking tasks, deferred TODOs, discovered bugs, follow-ups, dependencies, or "while I'm here" ideas. Triggers include "beads", "bd", "track this", "backlog", "file an issue", "what's ready to work on", or noticing work you're about to only keep in your head |
Using Beads
Overview
Core principle: In any git-hosted work, track it in beads — continuously, not as an
afterthought. bd is a git-native, dependency-aware issue tracker. Every task, deferred TODO,
discovered bug, and follow-up becomes a bead, so nothing is lost between sessions, ready-vs-blocked
work is always visible, and parallel agents (you, Codex, a future session) share one work-list.
The rule here is: always, and frequently. If you catch yourself holding a work item only in your
head or buried in a // TODO comment, that is the signal — make it a bead now.
Beads vs. the harness todo list: the in-session todo list is ephemeral scratch for this turn;
beads is the durable, git-shared, cross-session record. Use beads for anything that outlives the
current train of thought or that another agent might pick up.
The Habit
At the start of any git-hosted activity
bd ready
bd status
If the repo has no beads yet: bd init (fresh repo) or bd bootstrap (fresh clone of a repo that
already uses beads). Run bd prime any time you want the full, up-to-date agent workflow.
Capture the moment work appears
Don't defer capture. The builder's "write it down, don't do it" and the whittler's "that's
out of scope" are bead-creating moments:
bd create "Handle the empty-input edge case" -t task -p 2
bd q "Flaky test in writer_test — investigate"
bd create "Refactor parser" --deps discovered-from:hackinator-12
Model what blocks what
The whole payoff of beads is that ready work surfaces itself once dependencies are recorded:
bd dep add hackinator-5 hackinator-3
bd dep tree hackinator-5
Move work through its states
bd update hackinator-5 --status in_progress
bd comment hackinator-5 "Root cause was X"
bd close hackinator-5
Share it — it's git-hosted, so sync
bd sync
bd dolt push
With Parallel Agents
Beads is how a fan-out shares work without racing (see dispatching-subagents). Each agent can
atomically claim the next ready item instead of you hand-partitioning:
bd ready --claim --json
File the work as beads with dependencies, then let agents pull ready issues. Blocked work stays
hidden until its blocker closes.
Quick Reference
| Do | Command |
|---|
| See claimable work | bd ready |
| Create an issue | bd create "Title" -t task -p 2 |
| Quick capture (ID only) | bd q "Title" |
| Record a blocker | bd dep add <blocked> <blocker> |
| Claim / progress / finish | bd update <id> --status in_progress · bd comment <id> "…" · bd close <id> |
| Push to remote | bd sync (or bd dolt push) |
| Full agent workflow | bd prime |
When It's Overkill
Genuinely one-shot work in no repo, or throwaway scratch — skip it. Everywhere else in a git repo,
the default is on. When unsure, file the bead; a cheap bead beats a lost thought.
Common Mistakes
- Keeping work in your head or in code comments. That's the exact failure beads exists to prevent. File it.
- Batch-filing at the end. Capture as work appears — end-of-session recall drops the small stuff, which is most of it.
- Recording no dependencies. Beads without deps is just a list; the ready/blocked view is the point. Link blockers.
- Never syncing. Unpushed beads don't help the next session or another agent. Sync so the shared memory is actually shared.
