Skip to main content

​
Quickstart Guide

Get up and running with Beads in 2 minutes.
This guide assumes you’ve already installed Beads. If not, install it first:
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

​
Initialize Beads

1

Navigate to your project

cd your-project
2

Initialize Beads

bd init
The wizard will:
  • Create .beads/ directory and Dolt database
  • Prompt for your role (maintainer or contributor)
  • Import existing issues from git (if any)
  • Offer to install git hooks (recommended)
  • Auto-start Dolt server for database operations
3

Choose your role

When prompted: “Contributing to someone else’s repo? [y/N]”
  • Answer N if you’re the maintainer or have push access
  • Answer Y if you’re contributing to a fork
RoleUse CaseIssue Storage
maintainerRepo owner, team with push accessIn-repo .beads/
contributorFork contributor, OSS contributorSeparate planning repo
For team workflows with protected main branches, use:
bd init --branch beads-sync
This commits Beads data to a separate branch instead of main.

​
Create Your First Issues

Let’s create a few issues to get started: 
# Create a P1 task
bd create "Set up database" -p 1 -t task

# Create P2 features
bd create "Create API endpoints" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
Issue IDs are hash-based (e.g., bd-a1b2, bd-f14c) to prevent collisions when multiple agents/branches work concurrently.

​
With Descriptions

Add context with the --description flag: 
bd create "Set up database" -p 1 -t task \
  --description="Initialize PostgreSQL schema with users, posts, and comments tables"
For descriptions with special characters (backticks, quotes), use stdin: 
echo 'Description with `code blocks` and "quotes"' | bd create "Title" --description=-

​
View Your Issues

List all issues: 
bd list
Output: 
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API endpoints
○ bd-g25d [P2] [feature] - Add authentication
Symbol meanings:
  • ○ - Open
  • ◐ - In progress
  • ● - Closed
  • ✓ - Done
  • ❄ - Deferred

​
Add Dependencies

Create a dependency chain - API needs database, auth needs API: 
# API depends on database
bd dep add bd-f14c bd-a1b2

# Auth depends on API
bd dep add bd-g25d bd-f14c
Dependency syntax: bd dep add <child> <parent>The first ID (child) is blocked by the second ID (parent).

​
Visualize Dependencies

View the dependency tree: 
bd dep tree bd-g25d
Output: 
🌲 Dependency tree for bd-g25d:

→ bd-g25d: Add authentication [P2] (open)
  → bd-f14c: Create API endpoints [P2] (open)
    → bd-a1b2: Set up database [P1] (open)
You can see that bd-g25d is blocked by the entire chain!

​
Find Ready Work

Beads automatically identifies unblocked tasks: 
bd ready
Output: 
📋 Ready work (1 issues with no blockers):

1. [P1] bd-a1b2: Set up database
Only bd-a1b2 shows up because bd-f14c and bd-g25d are blocked!
bd ready uses blocker-aware semantics. It excludes:
  • Issues with open blocking dependencies
  • In-progress issues (already claimed)
  • Deferred issues
  • Blocked or hooked statuses

​
Work on a Task

1

Claim the task atomically

bd update bd-a1b2 --claim
This sets:
  • assignee to your git user
  • status to in_progress
The operation is atomic (compare-and-swap) to prevent race conditions.
2

Do the work

Implement the feature, fix the bug, write the code!
3

Complete the task

bd close bd-a1b2 --reason "Database schema initialized with migrations"
The task is now marked as closed.

​
Check Ready Work Again

Now that bd-a1b2 is closed: 
bd ready
Output: 
📋 Ready work (1 issues with no blockers):

1. [P2] bd-f14c: Create API endpoints
bd-f14c is now unblocked! 🎉
This is the core workflow: find ready work → claim → complete → next task becomes ready.

​
Working with Hierarchical Issues

For large features, organize work as epics: 
# Create an epic
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8

# Create child tasks (automatically get .1, .2, .3 suffixes)
bd create "Design login UI" -p 1 --parent bd-a3f8       # → bd-a3f8.1
bd create "Backend validation" -p 1 --parent bd-a3f8    # → bd-a3f8.2
bd create "Integration tests" -p 1 --parent bd-a3f8     # → bd-a3f8.3
View the hierarchy: 
bd dep tree bd-a3f8
Output: 
🌲 Dependency tree for bd-a3f8:

→ bd-a3f8: Auth System [epic] [P1] (open)
  → bd-a3f8.1: Design login UI [P1] (open)
  → bd-a3f8.2: Backend validation [P1] (open)
  → bd-a3f8.3: Integration tests [P1] (open)

​
By Priority

# Show only P0 (critical) work
bd ready --priority 0

# Show P1 and higher
bd list --priority 1

​
By Type

# Show only bugs
bd ready --type bug

# Show features
bd list --type feature

​
By Label

# Create issue with labels
bd create "Fix login bug" -l "backend,urgent" -p 0

# Filter by label
bd ready --label backend
bd ready --label-any backend,frontend  # Match any label

​
By Assignee

# Show only your work
bd list --assignee @me

# Show unassigned work
bd ready --unassigned

​
Track Progress

​
View Blocked Issues

bd blocked
Shows all blocked issues and what’s blocking them.

​
View Statistics

bd stats
Output: 
📊 Issue Statistics:

Total issues: 15
  Open: 8
  In Progress: 3
  Closed: 4

By Priority:
  P0: 1
  P1: 5
  P2: 9

By Type:
  feature: 8
  bug: 4
  task: 3

​
Sync with Team

If you installed git hooks during bd init, Beads auto-syncs on:
  • git pull
  • git push
  • git checkout
  • git merge

​
Manual Sync

Push changes to Dolt remote: 
bd dolt push
Pull changes from team: 
bd dolt pull
Dolt handles version control natively - no JSONL export/import needed!

​
AI Agent Workflow

For AI agents, use --json flag for programmatic access: 
bd ready --json
JSON output example: 
{
  "id": "bd-a1b2",
  "title": "Set up database",
  "status": "closed",
  "priority": 1,
  "type": "task",
  "assignee": "agent-1",
  "created": "2026-03-04T10:30:00Z",
  "updated": "2026-03-04T11:45:00Z"
}

​
Next Steps

Installation Guide

Detailed installation for all platforms and package managers

Essential Commands

Complete CLI reference with examples

Agent Instructions

Detailed guide for integrating Beads with AI agents

Advanced Features

Compaction, hierarchy, gates, and more

​
Common Patterns

​
Discovered Work Pattern

When implementing a feature, you often discover new work: 
# You're working on bd-a1b2
bd update bd-a1b2 --claim

# You discover a bug while implementing
bd create "Fix null pointer in auth" \
  -t bug -p 0 \
  --deps discovered-from:bd-a1b2 \
  --description="Found while implementing database setup"

# Close original work
bd close bd-a1b2 --reason "Complete, filed bd-x9y8 for bug found"

​
Planning Pattern

Break down a large feature: 
# 1. Create epic
bd create "User Dashboard" -t epic -p 1
# Returns: bd-d4sh

# 2. Create child tasks
bd create "Dashboard UI" --parent bd-d4sh -p 1
bd create "API endpoints" --parent bd-d4sh -p 1
bd create "Database queries" --parent bd-d4sh -p 1
bd create "Tests" --parent bd-d4sh -p 2

# 3. Add dependencies between children
bd dep add bd-d4sh.1 bd-d4sh.3  # UI depends on database
bd dep add bd-d4sh.2 bd-d4sh.3  # API depends on database
bd dep add bd-d4sh.4 bd-d4sh.1  # Tests depend on UI
bd dep add bd-d4sh.4 bd-d4sh.2  # Tests depend on API

# 4. View the plan
bd dep tree bd-d4sh

​
Bug Triage Pattern

# Critical bugs get P0
bd create "Auth bypass vulnerability" -t bug -p 0 -l security

# Important bugs get P1
bd create "Login fails on Safari" -t bug -p 1 -l browser,auth

# Find all P0 bugs
bd ready --priority 0 --type bug
Don’t use bd edit in automated scripts - it opens an interactive editor. Use bd update with flags instead.

​
Tips

  1. Always add descriptions - Future you (or your agent) will thank you
  2. Use labels liberally - They make filtering much easier
  3. Set up git hooks - Auto-sync saves manual work
  4. Use bd ready not bd list --ready - bd ready is blocker-aware
  5. Link discovered work - Use --deps discovered-from: to track context

Build docs developers (and LLMs) love

Get started for freeTalk to us