Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.
Also fixes stale comment in llms.txt ("Update status" → "Start work").
Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
5.9 KiB
Beads Quickstart
Get up and running with Beads in 2 minutes.
Installation
cd ~/src/beads
go build -o bd ./cmd/bd
./bd --help
Initialize
First time in a repository:
# Basic setup (prompts for contributor mode)
bd init
# Dolt backend (version-controlled SQL database)
bd init --backend dolt
# OSS contributor (fork workflow with separate planning repo)
bd init --contributor
# Team member (branch workflow for collaboration)
bd init --team
# Protected main branch (GitHub/GitLab)
bd init --branch beads-sync
The wizard will:
- Create
.beads/directory and database - Prompt for your role (maintainer or contributor) unless a flag is provided
- Import existing issues from git (if any)
- Prompt to install git hooks (recommended)
- Prompt to configure git merge driver (recommended)
- Auto-start Dolt server for database operations
Notes:
- SQLite backend stores data in
.beads/beads.db. - Dolt backend stores data in
.beads/dolt/and records"database": "dolt"in.beads/metadata.json. - Dolt backend uses a
dolt sql-serverfor database operations. - Dolt backend auto-commit defaults to OFF. Override with
bd --dolt-auto-commit off|on ...or config.
Role Configuration
During bd init, you'll be asked: "Contributing to someone else's repo? [y/N]"
- Answer Y if you're contributing to a fork (runs contributor wizard)
- Answer N if you're the maintainer or have push access
This sets git config beads.role which determines how beads routes issues:
| Role | Use Case | Issue Storage |
|---|---|---|
maintainer |
Repo owner, team with push access | In-repo .beads/ |
contributor |
Fork contributor, OSS contributor | Separate planning repo |
You can also configure manually:
# Set as contributor
git config beads.role contributor
# Set as maintainer
git config beads.role maintainer
# Check current role
git config --get beads.role
Note: If beads.role is not configured, beads falls back to URL-based detection (deprecated). Run bd doctor to check configuration status.
Your First Issues
# Create a few 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
# List them
./bd list
Note: Issue IDs are hash-based (e.g., bd-a1b2, bd-f14c) to prevent collisions when multiple agents/branches work concurrently.
Dependency visibility: When issues have blocking dependencies, bd list shows them inline:
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
This makes dependencies unmissable when reviewing epic subtasks.
Hierarchical Issues (Epics)
For large features, use hierarchical IDs to organize work:
# Create epic (generates parent hash ID)
./bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create child tasks (automatically get .1, .2, .3 suffixes)
./bd create "Design login UI" -p 1 # bd-a3f8e9.1
./bd create "Backend validation" -p 1 # bd-a3f8e9.2
./bd create "Integration tests" -p 1 # bd-a3f8e9.3
# View hierarchy
./bd dep tree bd-a3f8e9
Output:
🌲 Dependency tree for bd-a3f8e9:
→ bd-a3f8e9: Auth System [epic] [P1] (open)
→ bd-a3f8e9.1: Design login UI [P1] (open)
→ bd-a3f8e9.2: Backend validation [P1] (open)
→ bd-a3f8e9.3: Integration tests [P1] (open)
Add Dependencies
# API depends on database
./bd dep add bd-2 bd-1
# Auth depends on API
./bd dep add bd-3 bd-2
# View the tree
./bd dep tree bd-3
Output:
🌲 Dependency tree for bd-3:
→ bd-3: Add authentication [P2] (open)
→ bd-2: Create API [P2] (open)
→ bd-1: Set up database [P1] (open)
Find Ready Work
./bd ready
Output:
📋 Ready work (1 issues with no blockers):
1. [P1] bd-1: Set up database
Only bd-1 is ready because bd-2 and bd-3 are blocked!
Work the Queue
# Start working on bd-1
./bd update bd-1 --claim
# Complete it
./bd close bd-1 --reason "Database setup complete"
# Check ready work again
./bd ready
Now bd-2 is ready! 🎉
Track Progress
# See blocked issues
./bd blocked
# View statistics
./bd stats
Database Location
By default: ~/.beads/default.db
You can use project-specific databases:
./bd --db ./my-project.db create "Task"
Migrating Databases
After upgrading bd, use bd migrate to check for and migrate old database files:
# Inspect migration plan (AI agents)
./bd migrate --inspect --json
# Check schema and config
./bd info --schema --json
# Preview migration changes
./bd migrate --dry-run
# Migrate old databases to beads.db
./bd migrate
# Migrate and clean up old files
./bd migrate --cleanup --yes
AI agents: Use --inspect to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
Database Maintenance
As your project accumulates closed issues, the database grows. Manage size with these commands:
# View compaction statistics
bd admin compact --stats
# Preview compaction candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediately delete closed issues (CAUTION: permanent!)
bd admin cleanup --force
When to compact:
- Database file > 10MB with many old closed issues
- After major project milestones when old issues are no longer relevant
- Before archiving a project phase
Note: Compaction is permanent graceful decay. Original content is discarded but viewable via bd restore <id> from git history.
Next Steps
- Add labels:
./bd create "Task" -l "backend,urgent" - Filter ready work:
./bd ready --priority 1 - Search issues:
./bd list --status open - Detect cycles:
./bd dep cycles
See README.md for full documentation.