bd (Beads) Issue Tracking

Overview

bd is a dependency-aware issue tracker where issues chain together like beads. It uses Dolt (versioned MySQL) for storage with cell-level merge, and is optimized for AI agent workflows with JSON output, ready-work detection, and persistent memories.

When bd is present in a project (.beads/ directory exists), use it for ALL task tracking. Do NOT use TodoWrite, markdown TODOs, or external trackers alongside bd.

Prerequisites

bd CLI installed (bd version to check)
Initialized project: .beads/ directory exists (run bd init if not)
Git hooks installed: bd hooks install

Quick Command Reference

Action	Command
Session start context	`bd prime`
Find available work	`bd ready`
View issue	`bd show <id>`
List open issues	`bd list --status=open`
Create issue	`bd create --title="..." --description="..." -t task -p 2`
Claim work	`bd update <id> --claim`
Set in-progress	`bd update <id> --status=in_progress`
Close issue	`bd close <id> --reason="Done"`
Close multiple	`bd close <id1> <id2> ...`
Add dependency	`bd dep add <issue> <depends-on>`
Show blockers	`bd blocked`
Dependency tree	`bd dep tree <id>`
Search issues	`bd search "query"`
Store memory	`bd remember "insight" --key my-key`
Search memories	`bd memories <keyword>`
Recall memory	`bd recall <key>`
Pull from remote	`bd dolt pull`
Push to remote	`bd dolt push`
Health check	`bd doctor`
Project stats	`bd status`

Core Workflow

Step 0: Session Start

bd dolt pull              # Pull latest from remote
bd prime                  # Get workflow context (injected by hooks automatically)
bd ready                  # Find unblocked work

Step 1: Claim Work

bd show <id>              # Review issue details and dependencies
bd update <id> --claim    # Atomically claim (sets assignee + in_progress; fails if already claimed)

--claim is atomic -- if another agent already claimed the issue, the command fails. This prevents duplicate work.

Step 2: Create Issues

Create issues BEFORE writing code. Issue-first workflow ensures traceability.

# Basic task
bd create --title="Fix login validation" \
  --description="Email regex allows invalid domains" \
  -t bug -p 1

# Discovered during other work
bd create --title="Add unit tests for auth" \
  --description="Cover edge cases found during review" \
  -t task -p 2 --deps discovered-from:<parent-id>

# Epic with children
bd create --title="Refactor auth module" -t epic -p 1
bd create --title="Extract JWT service" -t task --parent <epic-id>
bd create --title="Add token rotation" -t task --parent <epic-id>

Issue types: bug, feature, task, epic, chore, decision

Priority scale (numeric only, never strings):

Value	Meaning	Use For
0	Critical	Security, data loss, broken builds
1	High	Major features, important bugs
2	Medium	Default, standard work
3	Low	Polish, optimization
4	Backlog	Future ideas

Step 3: Manage Dependencies

# bd-B depends on bd-A (bd-A must finish before bd-B can start)
bd dep add <blocked-id> <blocker-id>

# Shorthand: bd-A blocks bd-B
bd dep <blocker-id> --blocks <blocked-id>

# Inspect
bd blocked                    # All blocked issues
bd dep tree <id>              # Visualize dependency tree
bd dep cycles                 # Detect circular dependencies
bd dep list <id>              # List dependencies of an issue

# Remove
bd dep remove <issue> <dependency>

Dependency types:

Type	Semantics
`blocks`	Must complete first (hard blocker)
`related`	Soft connection, no blocking
`parent-child`	Epic/subtask hierarchy
`discovered-from`	Auto-link when finding related work during implementation

Step 4: Update Issues

bd update <id> --title="New title"
bd update <id> --description="Updated description"
bd update <id> --priority 0              # Escalate to critical
bd update <id> --assignee alice
bd update <id> --status=in_progress
bd update <id> --notes="Found root cause in auth.go"
bd update <id> --append-notes="Additional finding"
bd update <id> --design="Use strategy pattern for providers"
bd update <id> --acceptance="Login rejects invalid emails"
bd update <id> --add-label backend
bd update <id> --remove-label wip
bd update <id> --due "+2d"               # Due in 2 days
bd update <id> --defer "+1w"             # Hide from bd ready for 1 week
bd update <id> --estimate 120            # 120 minutes

Step 5: Complete Work

bd close <id> --reason="Implemented in commit abc123"
bd close <id1> <id2> <id3>          # Batch close (more efficient)
bd close <id> --suggest-next         # Show newly unblocked work after closing

Step 6: Session Close

bd close <completed-ids>             # Close finished work
bd dolt pull                         # Pull latest beads
git add . && git commit -m "..."     # Commit code
git push                             # Push code to remote
bd dolt push                         # Push beads to remote

Persistent Memories

Memories survive across sessions and account rotations. Use instead of MEMORY.md files.

bd remember "always run tests with -race flag"
bd remember "auth module uses JWT not sessions" --key auth-jwt
bd memories                    # List all
bd memories "auth"             # Search by keyword
bd recall auth-jwt             # Retrieve specific memory
bd forget auth-jwt             # Remove a memory

Searching and Filtering

# Text search (excludes closed by default)
bd search "authentication"
bd search "bug" --status all              # Include closed
bd search "api" --desc-contains "endpoint"
bd search "login" --assignee alice
bd search "perf" --priority-min 0 --priority-max 2

# Filtered listing
bd list --status=open --type=bug
bd list --assignee=alice --priority 0
bd list --label backend --sort priority
bd list --created-after 2025-01-01
bd list --overdue                         # Past due date
bd list --all                             # Include closed
bd list --parent <epic-id>                # Children of epic
bd list --no-assignee                     # Unclaimed work

Epics and Hierarchy

bd create --title="Auth overhaul" -t epic -p 1
bd create --title="Subtask 1" -t task --parent <epic-id>
bd children <epic-id>                     # List children
bd epic status <epic-id>                  # Completion stats
bd epic close-eligible                    # Close epics where all children done

Dolt Sync (Version Control for Issues)

bd uses Dolt for versioned, mergeable issue storage across machines and teams.

bd dolt pull          # Pull remote changes
bd dolt push          # Push local changes
bd dolt commit        # Commit pending changes
bd dolt status        # Server status
bd dolt show          # Config + connection test
bd dolt start         # Start Dolt server
bd dolt stop          # Stop Dolt server
bd dolt killall       # Kill orphan Dolt processes

Maintenance

bd doctor             # Health check (schema, hooks, versions, permissions)
bd status             # Database overview and statistics
bd gc                 # Garbage collect old issues, compact Dolt history
bd stale              # Find stale issues not updated recently
bd hooks install      # Install/reinstall git hooks

Rules

Always use --json flag when parsing output programmatically
Always create issues before writing code (issue-first workflow)
Always run bd dolt pull at session start
Never use bd edit -- it opens an interactive editor that blocks agents
Never use TodoWrite or markdown files for task tracking when bd is active
Never use string priorities like "high"/"medium" -- use 0-4 or P0-P4
Link discovered work with --deps discovered-from:<parent-id>
Close issues with --reason to preserve context for future sessions
Use bd remember for persistent insights, not MEMORY.md files
When creating many issues, use parallel subagents for efficiency

Troubleshooting

Symptom	Fix
`bd ready` returns nothing but issues exist	Check `bd list --status=open` -- issues may be blocked, in_progress, or deferred
Dependency cycle detected	`bd dep cycles` to locate, `bd dep remove` to break the cycle
Database not found	Run `bd init` or verify `.beads/*.db` exists
Dolt server won't start	`bd dolt killall` then `bd dolt start`
Stale data after git pull	`bd dolt pull` to sync beads (separate from git)
Hooks not firing	`bd hooks install` to reinstall git hooks
Schema errors	`bd doctor` to diagnose, `bd migrate` if schema is outdated
Issue ID conflicts	bd uses hash-based IDs to avoid conflicts across agents

Bd Issue Tracking