Apply findings from docs/GETTING_STARTED_ANALYSIS.md: - installation.md (261->81): Remove IDE section (duplicates ide-setup.md), remove updating section (duplicates upgrading.md), consolidate platforms, move CGO/build deps below happy path - quickstart.md (370->115): Remove Notion sync, database maintenance, database migration, database location sections. Trim role config and init options. Keep core flow: init, create, deps, ready, work, sync - ide-setup.md (204->80): Remove bd prime internals, trim MCP duplication, condense per-editor sections to command + verify pattern - upgrading.md (135->39): Consolidate table with detailed sections, trim troubleshooting to essentials Total: 970 lines -> 315 lines (3.1x reduction) Closes #3245
3 KiB
| id | title | sidebar_position |
|---|---|---|
| quickstart | Quick Start | 2 |
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 Sync for details.
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: Dependencies
- IDE integration: IDE Setup
- Full command list: CLI Reference