beads
Dolt-powered issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. Trigger with "create task", "what's ready", "track this work", "resume after compaction".
By gastownhall · 1,855 installs
npx skills add gastownhall/beads --skill beads
Source repository · Upstream listing
Beads
Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
First Step
Run:
If that prints nothing, check whether the repository has an active Beads workspace:
Preferred Route
Use the bd CLI when shell access is available. It is the most compact and direct Beads interface.
Core CLI Workflow
1. Find work:
2. Inspect before editing:
3. Claim work atomically:
4. Create durable follow up work when implementation reveals new tasks:
5. Close completed work:
What Belongs In Beads
Use Beads for:
shared project tasks
blockers and dependencies
discovered follow up work
work that must survive thread reset, compaction, or handoff
status that another person or agent should be able to resume
Use agent local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
Rules
Do not create markdown TODO files as the source of truth when Beads is available.
Do not use bd edit ; it opens an interactive editor. Use bd update flags instead.
Prefer json when parsing bd output programmatically.
If hooks are installed, bd prime may already be injected. Run it manually when context is missing.
Do not auto close or mutate tasks unless the work is actually complete.