website/docs/getting-started/quickstart.md
Get up and running with Beads in a few minutes.
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
Beads tracks dependencies between issues and computes a ready queue — only items with no active blockers appear. Here's the difference:
Flat tracker (GitHub Issues):
Open issues: Set up database, Create API, Add authentication
→ An agent picks "Add authentication" and gets stuck immediately
Beads:
$ 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. No wasted cycles.
Install bd using the full installation guide (Homebrew, install script, npm, or go install).
Developing in a clone of this repository: use make install so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc go build / go install without the Makefile unless you know what you are doing — see the repository README and AGENTS.md.
bd --help
First time in a repository:
# Basic setup (prompts for contributor mode)
bd init
# For AI agents (non-interactive)
bd init --quiet
# 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)
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
The wizard will:
.beads/ directory and embedded Dolt databaseNotes:
.beads/embeddeddolt/.bd init --server to connect to a dolt sql-server instead.bd init --from-jsonl.During bd init, you'll be asked: "Contributing to someone else's repo? [y/N]"
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.
# 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.
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 (use --parent to attach to the epic)
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # 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)
# 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)
Dependency visibility: bd list shows blocking dependencies 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)
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.
Understanding why: Use --explain to see the full graph reasoning:
bd ready --explain
Output:
Ready Work Explanation
● Ready (1 issues):
bd-1 [P1] Set up database
Reason: no blocking dependencies
Unblocks: 1 issue(s)
● Blocked (2 issues):
bd-2 [P2] Create API
← blocked by bd-1: Set up database [open]
bd-3 [P2] Add authentication
← blocked by bd-2: Create API [open]
─ Summary: 1 ready, 2 blocked
Note: 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.
# 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.
# See blocked issues
bd blocked
# View statistics
bd stats
Share issues with your team using Dolt remotes. Dolt stores data under refs/dolt/data on the same Git remote, separate from standard Git refs.
# Add a remote (GitHub example — also supports DoltHub, S3, GCS, local paths)
bd dolt remote add origin git+ssh://[email protected]/org/repo.git
# Push your issues
bd dolt push
# Pull teammates' changes
bd dolt pull
When a teammate clones the repo, bd bootstrap auto-detects the existing database on refs/dolt/data and clones it — no manual remote setup needed.
See Sync for CLI details. For remote configuration and federation, see the repository docs DOLT-BACKEND.md and FEDERATION-SETUP.md.
If you keep project issues in Notion, save an integration token first:
bd config set notion.token <your-token>
Then either create a new Beads database under a parent page or connect to an existing target:
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
The same auth value can also come from NOTION_TOKEN. Directly setting notion.data_source_id remains available as an escape hatch for advanced setups.
Check which auth source is active and whether the target schema is ready:
bd notion status
bd notion status --json
Preview or run sync:
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
By default (embedded mode), data is stored in .beads/embeddeddolt/ within your repository.
In server mode, data is managed by the external dolt sql-server.
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.
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:
Note: Compaction is permanent graceful decay. Original content is discarded but viewable via bd restore <id> from git history.
bd create "Task" -l "backend,urgent"bd ready --priority 1bd ready --explainbd graph checkbd list --status openbd dep cyclesSee the repository README for an overview and links to deeper docs.