What problem does it solve?
Beads enables tracking of complex, multi-session work with dependency graphs and persistent context across compaction cycles. It is ideal for tasks that span days or weeks and require memory across interruptions; for simple single-session tasks, use TodoWrite.
Core Features & Use Cases
- Graph-based issue tracker: manage issues, notes, dependencies, and statuses with long-term context.
- Cross-session continuity: preserves memory across compaction events so you can resume with full context.
- Dependency awareness: supports blocks, related, parent-child, and discovered-from relationships to model complex work.
- Surviving compaction: critical notes and history survive compaction, enabling safe post-compaction recovery.
- Decision journaling: structured notes with completions, in-progress state, blockers, and decisions for future you.
Quick Start
Create a beads issue and populate the notes with a resumable state, e.g.:
- bd create "Research contract clauses" -p 2
- bd update <issue-id> --notes "COMPLETED: contract clause shortlist; IN PROGRESS: draft negotiation terms; BLOCKERS: legal review pending; NEXT: lock in final terms" --json
After weeks or days, use
bd show <issue-id> --json to reconstruct full context.