Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

bd vs TodoWrite

bd (persistent)	TodoWrite (ephemeral)
Multi-session work	Single-session tasks
Complex dependencies	Linear execution
Survives compaction	Conversation-scoped
Git-backed, team sync	Local to session

Decision test: "Will I need this context in 2 weeks?" → YES = bd

When to use bd:

Work spans multiple sessions or days
Tasks have dependencies or blockers
Need to survive conversation compaction
Exploratory/research work with fuzzy boundaries
Collaboration with team (git sync)

When to use TodoWrite:

Single-session linear tasks
Simple checklist for immediate work
All context is in current conversation
Will complete within current session

Prerequisites

bd --version  # Requires v0.34.0+

bd CLI installed and in PATH
Git repository (bd requires git for sync)
Initialization: bd init run once (humans do this, not agents)

CLI Quick Reference

Essential Commands

# Find ready work (no blockers)
bd ready --json

# Create new issue
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json

# Update issue status
bd update <id> --status in_progress --json

# Complete work
bd close <id> --reason "Done" --json

# Show issue details
bd show <id> --json

# List issues
bd list --json

# Sync to git (always run at session end)
bd sync

Dependencies

# Add dependency (child blocks on parent)
bd dep add <child> <parent>

# Link discovered work
bd dep add <discovered-id> <parent-id> --type discovered-from

# Show dependency tree
bd dep tree <id>

# Find blocked issues
bd blocked

Issue Types

bug - Something broken that needs fixing
feature - New functionality
task - Work item (tests, docs, refactoring)
epic - Large feature composed of multiple issues
chore - Maintenance work (dependencies, tooling)

Priorities

0 - Critical (security, data loss, broken builds)
1 - High (major features, important bugs)
2 - Medium (nice-to-have features, minor bugs)
3 - Low (polish, optimization)
4 - Backlog (future ideas)

Dependency Types

blocks - Hard dependency (issue X blocks issue Y)
related - Soft relationship (issues are connected)
parent-child - Epic/subtask relationship
discovered-from - Track issues discovered during work

Only blocks dependencies affect the ready work queue.

Session Protocol

bd ready --json — Find unblocked work
bd show <id> --json — Get full context
bd update <id> --status in_progress --json — Start work
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." --json — Complete task
bd sync — Persist to git (always run at session end)

Hierarchical Issues (Epics)

For large features, use hierarchical IDs:

# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1 --json
# Returns: bd-a3f8e9

# Create child tasks (auto-numbered .1, .2, .3)
bd create "Design login UI" -p 1 --json       # bd-a3f8e9.1
bd create "Backend validation" -p 1 --json    # bd-a3f8e9.2
bd create "Integration tests" -p 1 --json     # bd-a3f8e9.3

# View hierarchy
bd dep tree bd-a3f8e9

Hash-Based IDs

bd uses hash-based IDs (e.g., bd-a1b2, bd-f14c) to prevent collisions when multiple agents/branches work concurrently. This is different from sequential IDs - each issue gets a unique hash that won't conflict on merge.

Time-Based Scheduling

# Create with due date and defer
bd create "Task" --due=+6h --json              # Due in 6 hours
bd create "Task" --defer=tomorrow --json       # Hidden until tomorrow

# Query by time
bd list --deferred --json          # Show deferred issues
bd list --overdue --json           # Due date in past
bd list --due-before=+2d --json    # Due within 2 days

Landing the Plane

When finishing a session, always:

Close finished issues with bd close <id> --reason "..."
File any remaining work as new issues
Run bd sync to persist to git
If requested, push to remote: git push

Git Integration

bd automatically:

Exports to JSONL after CRUD operations (30-second debounce)
Imports from JSONL when it's newer than DB (e.g., after git pull)

For immediate sync without waiting:

bd sync  # Force export/import/commit/push

Commit Message Convention

Include issue ID in commit messages for traceability:

git commit -m "Fix auth validation bug (bd-abc)"

Best Practices for Agents

Always use --json flags for programmatic use
Link discoveries with discovered-from to maintain context
Check bd ready --json before asking "what next?"
Run bd sync before ending sessions
Use bd dep tree to understand complex dependencies
Priority 0-1 issues are usually more important than 2-4

Advanced Features

Feature	CLI	Description
Molecules (templates)	`bd mol --help`	Proto definitions, component labels
Chemistry (pour/wisp)	`bd pour`, `bd wisp`	Task decomposition patterns
Agent beads	`bd agent --help`	Agent bead tracking
Async gates	`bd gate --help`	Human-in-the-loop gates
Worktrees	`bd worktree --help`	Parallel development patterns

Troubleshooting

Database feels stale after git pull

bd ready --json  # Auto-imports fresh data
# or explicit:
bd sync

Multiple projects

Each project is isolated with its own .beads/ directory. bd auto-discovers based on current directory.

Protected branches

bd init --branch beads-metadata  # Commit to separate branch

Full Documentation

bd prime: AI-optimized workflow context (run bd prime)
GitHub: https://github.com/steveyegge/beads
FAQ: https://github.com/steveyegge/beads/blob/main/docs/FAQ.md