Skip to main content
Version: 1.0.0

Beads Quick Start

Get up and running with beads in a few minutes.

Why Beads?​

Flat issue trackers show you all open items. You pick one - but if it depends on something else that isn't done yet, you've wasted time. Beads tracks dependencies between issues and computes a ready queue - only items with no active blockers appear.

$ bd ready
1. [P1] [task] bd-1: Set up database

$ bd ready --explain --json | jq '.blocked[0]'
{
  "id": "bd-3",
  "title": "Add authentication",
  "blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}

The agent picks the right task every time.

Initialize​

cd your-project
bd init          # Interactive setup (prompts for role)
bd init --quiet  # Non-interactive (for AI agents)

The wizard creates .beads/, sets up the embedded Dolt database, and optionally installs git hooks. During init, you'll be asked whether you're a maintainer or contributor - this determines how beads routes issues. You can change it later with git config beads.role.

Create Issues and Dependencies​

# Create issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature

# Add dependencies (API needs database, auth needs API)
bd dep add bd-2 bd-1
bd dep add bd-3 bd-2

# View the dependency tree
bd dep tree bd-3

Issue IDs are hash-based (e.g., bd-a1b2) to prevent collisions when multiple agents work concurrently.

Find and Work the Ready Queue​

# What's unblocked right now?
bd ready

# Why is something blocked?
bd ready --explain

# Claim and complete work
bd update bd-1 --claim
bd close bd-1 --reason "Database setup complete"

# Now bd-2 is ready
bd ready

bd ready is not the same as bd list --status open - the list command shows all open issues regardless of blockers. The ready command computes the dependency graph and only shows truly unblocked work.

Epics​

Group related work under an epic:

bd create "Auth System" -t epic -p 1       # Returns: bd-a3f8e9
bd create "Design login UI" -p 1 --parent bd-a3f8e9
bd create "Backend validation" -p 1 --parent bd-a3f8e9
bd dep tree bd-a3f8e9

Team Sync​

Share issues using Dolt remotes (works over the same Git remote):

bd dolt remote add origin git+ssh://git@github.com/org/repo.git
bd dolt push
bd dolt pull

When a teammate clones the repo, bd bootstrap auto-detects the existing database. See bd dolt for sync commands.

Track Progress​

bd blocked    # See blocked issues
bd stats      # Project statistics
bd list       # All issues
bd doctor     # Health check

Next Steps​

  • Add labels: bd create "Task" -l "backend,urgent"
  • Filter ready work: bd ready --priority 1
  • Check graph integrity: bd graph check
  • Gates for PR/CI sync: bd gate
  • IDE integration: IDE Setup
  • Full command list: CLI Reference