beads

Beads (br) is a specialized graph-based issue tracking tool designed to address the volatility of AI agent context. Unlike standard linear todo lists that reset during conversation compaction, Beads provides persistent memory for multi-session work. It is specifically built for long-running software engineering projects where tasks have complex dependencies, blockers, and require high-fidelity state recovery. By utilizing Git-backed storage, it ensures that your project's roadmap, notes, and task progress remain synchronized and accessible across different coding sessions and team members.

• Enables persistent memory that survives conversation compaction and context resets.

• Implements graph-based task dependency management to track blockers and sequence complex workflows.

• Integrates with Git, allowing issue state (SQLite-based) to be exported to JSONL and tracked via version control.

• Supports multi-user team synchronization by leveraging standard Git workflows.

• Facilitates session handoff by providing a structured protocol for updating status, capturing work notes, and context recovery.

• Operates as a command-line interface (CLI) optimized for AI agents to autonomously manage their own task lists.

• Use Beads when work spans multiple days or sessions, or when context is too critical to lose during compaction.

• Use the br CLI commands such as br ready to find unblocked work, br update to transition states, and br sync to commit changes to your repository.

• Always define dependencies using the br dep add command to clarify the order of operations, noting that the directionality signifies that the second argument must complete before the first.

• Ensure the .beads/ directory is present in your repository; if missing after a fresh clone, hydrate the database using br sync --import-only.

• Prefer Beads over ephemeral tools like TodoWrite when tasks have fuzzy boundaries, research components, or require persistent historical tracking of decisions made during development.