Beads Issue Tracker (bd)
Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
Getting Started
bd init # Initialize bd in your project
bd init --prefix api # Initialize with custom prefix (api-1, api-2)
Creating Issues
bd create "Fix login bug"
bd create "Add auth" -p 0 -t feature
bd create "Write tests" -d "Unit tests for auth" --assignee alice
Viewing Issues
bd list # List all issues
bd list --status open # List by status
bd list --priority 0 # List by priority (0-4, 0=highest)
bd show bd-1 # Show issue details
Managing Dependencies
bd dep add bd-1 bd-2 # Add dependency (bd-2 blocks bd-1)
bd dep tree bd-1 # Visualize dependency tree
bd dep cycles # Detect circular dependencies
Dependency Types:
blocks- Task B must complete before task Arelated- Soft connection, doesn't block progressparent-child- Epic/subtask hierarchical relationshipdiscovered-from- Auto-created when AI discovers related work
Ready Work
bd ready # Show issues ready to work on
Ready = status is 'open' AND no blocking dependencies. Perfect for agents to claim next work!
Updating Issues
bd update bd-1 --status in_progress
bd update bd-1 --priority 0
bd update bd-1 --assignee bob
Closing Issues
bd close bd-1
bd close bd-2 bd-3 --reason "Fixed in PR #42"
Database Location
bd automatically discovers your database:
--db /path/to/db.dbflag$BEADS_DBenvironment variable.beads/*.dbin current directory or ancestors~/.beads/default.dbas fallback
Agent Integration
bd is designed for AI-supervised workflows:
- Agents create issues when discovering new work
bd readyshows unblocked work ready to claim- Use
--jsonflags for programmatic parsing - Dependencies prevent agents from duplicating effort
Git Workflow (Auto-Sync)
bd automatically keeps git in sync:
- Export to JSONL after CRUD operations (5s debounce)
- Import from JSONL when newer than DB (after git pull)
- Works seamlessly across machines and team members
Disable with: --no-auto-flush or --no-auto-import