> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get up and running with Beads in 2 minutes - create your first issues, add dependencies, and find ready work
# Quickstart Guide
Get up and running with Beads in 2 minutes.
This guide assumes you've already [installed Beads](/installation). If not, install it first:
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```
## Initialize Beads
```bash theme={null}
cd your-project
```
```bash theme={null}
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
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
| Role | Use Case | Issue Storage |
| ------------- | --------------------------------- | ---------------------- |
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
For team workflows with protected main branches, use:
```bash theme={null}
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:
```bash theme={null}
# 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:
```bash theme={null}
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:
```bash theme={null}
echo 'Description with `code blocks` and "quotes"' | bd create "Title" --description=-
```
## View Your Issues
List all issues:
```bash theme={null}
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:
```bash theme={null}
# 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 `
The first ID (child) is blocked by the second ID (parent).
## Visualize Dependencies
View the dependency tree:
```bash theme={null}
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:
```bash theme={null}
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
```bash theme={null}
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.
Implement the feature, fix the bug, write the code!
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
# 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:
```bash theme={null}
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)
```
## Filter and Search
### By Priority
```bash theme={null}
# Show only P0 (critical) work
bd ready --priority 0
# Show P1 and higher
bd list --priority 1
```
### By Type
```bash theme={null}
# Show only bugs
bd ready --type bug
# Show features
bd list --type feature
```
### By Label
```bash theme={null}
# 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
```bash theme={null}
# Show only your work
bd list --assignee @me
# Show unassigned work
bd ready --unassigned
```
## Track Progress
### View Blocked Issues
```bash theme={null}
bd blocked
```
Shows all blocked issues and what's blocking them.
### View Statistics
```bash theme={null}
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:
```bash theme={null}
bd dolt push
```
Pull changes from team:
```bash theme={null}
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:
```bash Check for work theme={null}
bd ready --json
```
```bash Claim task theme={null}
bd update bd-a1b2 --claim --json
```
```bash Discover work theme={null}
echo 'Found edge case in auth flow' | \
bd create "Handle expired tokens" \
--deps discovered-from:bd-a1b2 \
--description=- \
--json
```
```bash Complete work theme={null}
bd close bd-a1b2 --reason "Implemented with tests" --json
```
JSON output example:
```json theme={null}
{
"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
Detailed installation for all platforms and package managers
Complete CLI reference with examples
Detailed guide for integrating Beads with AI agents
Compaction, hierarchy, gates, and more
## Common Patterns
### Discovered Work Pattern
When implementing a feature, you often discover new work:
```bash theme={null}
# 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:
```bash theme={null}
# 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
```bash theme={null}
# 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