Beads

Beads Issue Tracker

Git-backed issue tracking with dependency awareness. Perfect for agent task management.

Prerequisites

Install beads:

# Install via cargo or download binary
cargo install beads
# Or download from releases

Initialize in a project:

bd init

CLI Reference

View Ready Work

# Get issues with no blockers
bd ready --json

# Filter by assignee
bd ready --assignee username --json

# Filter by label
bd ready --label "urgent" --json

# Limit results
bd ready --limit 5 --json

Create Issues

# Basic task
bd create "Task title" --json

# With details
bd create "Task title" -d "Description" -t task -p 2 --json

# As subtask of epic
bd create "Subtask" --parent epic-123 --force --json

# With dependencies
bd create "Task" --deps "other-issue-id" --json

# Quick mode (less output)
bd create "Task" -q --json

Issue Types

• bug - Bug reports
• feature - New features
• task - General tasks
• epic - Parent containers
• chore - Maintenance work

Priority Levels

• 0 - Critical
• 1 - High
• 2 - Normal (default)
• 3 - Low
• 4 - Backlog

Update Issues

# Change status
bd update issue-id -s in_progress --json

# Add notes
bd update issue-id --notes "Progress update" --json

# Change priority
bd update issue-id -p 1 --json

# Add labels
bd update issue-id --add-label "urgent" --json

Close Issues

# Close with reason
bd close issue-id -r "Completed successfully" --json

List Issues

# All open issues
bd list --status open --json

# Filter by type
bd list --type bug --json

# Filter by assignee
bd list --assignee "username" --json

# Filter by label
bd list --label "backend" --json

# Filter by priority
bd list --priority 1 --json

Show Issue Details

bd show issue-id --json

Dependencies

# Add dependency (issue-a depends on issue-b)
bd dep add issue-a issue-b

# Dependency types: blocks, related, parent-child, discovered-from
bd dep add issue-a issue-b -t blocks

Sync with Git

# Sync issues to git remote
bd sync

Hygiene Commands

# Find duplicate issues
bd duplicates --dry-run

# Auto-merge duplicates
bd duplicates --auto-merge

# Find stale issues (no activity)
bd stale --days 14 --json

# Cleanup old closed issues
bd cleanup --dry-run
bd cleanup -f

Install Git Hooks

# Auto-sync on commit
bd hooks install

System Info

# Check version
bd --version

# Project info
bd info --json

Workflow Patterns

Session Start

# See what's ready to work on
bd ready --json

Working on a Task

# Start working
bd update task-id -s in_progress --json

# Add progress notes
bd update task-id --notes "Halfway done" --json

# Complete
bd close task-id -r "Implemented and tested" --json

Epic Planning

# Create epic
bd create "User Authentication" -t epic --json

# Add subtasks
bd create "Design auth flow" --parent auth-epic --force --json
bd create "Implement login" --parent auth-epic --force --json
bd create "Add tests" --parent auth-epic --force --json

# Add dependencies between subtasks
bd dep add implement-id design-id -t blocks
bd dep add tests-id implement-id -t blocks

End of Session

# Sync to git
bd sync

Worktree Mode

When using git worktrees, disable the daemon:

export BEADS_NO_DAEMON=1
# Or per-command
bd --no-daemon ready --json

Best Practices

1. Always use `--json` for parseable output 2. Use `bd ready` at session start to see unblocked work 3. Add dependencies to express task relationships 4. Use epics for grouping related tasks 5. Run `bd sync` before ending sessions 6. Install hooks for automatic sync: bd hooks install