bd Issue Tracking

Overview

bd is a graph-based issue tracker for persistent memory across sessions. Use for multi-session work with complex dependencies; use TodoWrite for simple single-session tasks.

When to Use bd vs TodoWrite

Use bd when:

• Multi-session work - Tasks spanning multiple compaction cycles or days
• Complex dependencies - Work with blockers, prerequisites, or hierarchical structure
• Knowledge work - Strategic documents, research, or tasks with fuzzy boundaries
• Side quests - Exploratory work that might pause the main task
• Project memory - Need to resume work after weeks away with full context

Use TodoWrite when:

• Single-session tasks - Work that completes within current session
• Linear execution - Straightforward step-by-step tasks with no branching
• Immediate context - All information already in conversation
• Simple tracking - Just need a checklist to show progress

Key insight: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient.

Test Yourself: bd or TodoWrite?

Ask these questions to decide:

Choose bd if:

• ❓ "Will I need this context in 2 weeks?" → Yes = bd
• ❓ "Could conversation history get compacted?" → Yes = bd
• ❓ "Does this have blockers/dependencies?" → Yes = bd
• ❓ "Is this fuzzy/exploratory work?" → Yes = bd

Choose TodoWrite if:

• ❓ "Will this be done in this session?" → Yes = TodoWrite
• ❓ "Is this just a task list for me right now?" → Yes = TodoWrite
• ❓ "Is this linear with no branching?" → Yes = TodoWrite

When in doubt: Use bd. Better to have persistent memory you don't need than to lose context you needed.

For detailed decision criteria and examples, read: references/BOUNDARIES.md

Surviving Compaction Events

Critical: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory.

What survives compaction:

• All bead data (issues, notes, dependencies, status)
• Complete work history and context

What doesn't survive:

• Conversation history
• TodoWrite lists
• Recent discussion context

Writing notes for post-compaction recovery:

Write notes as if explaining to a future agent with zero conversation context:

Pattern:

notes field format:
- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting")
- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template")
- BLOCKERS: What's preventing progress
- KEY DECISIONS: Important context or user guidance

After compaction: bd show <issue-id> reconstructs full context from notes field.

Notes Quality Self-Check

Before checkpointing (especially pre-compaction), verify your notes pass these tests:

❓ Future-me test: "Could I resume this work in 2 weeks with zero conversation history?"

• What was completed? (Specific deliverables, not "made progress")
• What's in progress? (Current state + immediate next step)
• What's blocked? (Specific blockers with context)
• What decisions were made? (Why, not just what)

❓ Stranger test: "Could another developer understand this without asking me?"

• Technical choices explained (not just stated)
• Trade-offs documented (why this approach vs alternatives)
• User input captured (decisions that came from discussion)

Good note example:

COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens)
KEY DECISION: RS256 over HS256 per security review - enables key rotation
IN PROGRESS: Password reset flow - email service working, need rate limiting
BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off)
NEXT: Implement rate limiting (5 attempts/15min) once expiry decided

Bad note example:

Working on auth. Made some progress. More to do.

For complete compaction recovery workflow, read: references/WORKFLOWS.md

Session Start Protocol

bd is available when:

• Project has a .beads/ directory (project-local database), OR
• ~/.beads/ exists (global fallback database for any directory)

At session start, always check for bd availability and run ready check.

Session Start Checklist

Copy this checklist when starting any session where bd is available:

Session Start:
- [ ] Run bd ready --json to see available work
- [ ] Run bd list --status in_progress --json for active work
- [ ] If in_progress exists: bd show <issue-id> to read notes
- [ ] Report context to user: "X items ready: [summary]"
- [ ] If using global ~/.beads, mention this in report
- [ ] If nothing ready: bd blocked --json to check blockers

Pattern: Always check both bd ready AND bd list --status in_progress. Read notes field first to understand where previous session left off.

Report format:

• "I can see X items ready to work on: [summary]"
• "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"

This establishes immediate shared context about available and active work without requiring user prompting.

For detailed collaborative handoff process, read: references/WORKFLOWS.md

Note: bd auto-discovers the database:

• Uses .beads/*.db in current project if exists
• Falls back to ~/.beads/default.db otherwise
• No configuration needed

When No Work is Ready

If bd ready returns empty but issues exist:

bd blocked --json

Report blockers and suggest next steps.

Progress Checkpointing

Update bd notes at these checkpoints (don't wait for session end):

Critical triggers:

• ⚠️ Context running low - User says "running out of context" / "approaching compaction" / "close to token limit"
• 📊 Token budget > 70% - Proactively checkpoint when approaching limits
• 🎯 Major milestone reached - Completed significant piece of work
• 🚧 Hit a blocker - Can't proceed, need to capture what was tried
• 🔄 Task transition - Switching issues or about to close this one
• ❓ Before user input - About to ask decision that might change direction

Proactive monitoring during session:

• At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?"
• At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd"
• At 90% token usage: Automatically checkpoint without asking

Current token usage: Check <system-warning>Token usage: messages to monitor proactively.

Checkpoint checklist:

Progress Checkpoint:
- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
- [ ] Document KEY DECISIONS or BLOCKERS since last update
- [ ] Mark current status (in_progress/blocked/closed)
- [ ] If discovered new work: create issues with discovered-from
- [ ] Verify notes are self-explanatory for post-compaction resume

Most important: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.

Test yourself: "If compaction happened right now, could future-me resume from these notes?"

Database Selection

bd automatically selects the appropriate database:

• Project-local (.beads/ in project): Used for project-specific work
• Global fallback (~/.beads/): Used when no project-local database exists

Use case for global database: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.

When to use --db flag explicitly:

• Accessing a specific database outside current directory
• Working with multiple databases (e.g., project database + reference database)
• Example: bd --db /path/to/reference/terms.db list

Database discovery rules:

• bd looks for .beads/*.db in current working