Skip to main content
Get up and running with Beads in a few minutes.

​
Why Beads?

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.

​
Installation

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

​
Initialize

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:
  • Create .beads/ directory and embedded Dolt database
  • Prompt for your role (maintainer or contributor) unless a flag is provided
  • Import existing issues from git (if any)
  • Install git hooks (skip with --skip-hooks)
Notes:
  • Dolt is the default (and only) storage backend. Data is stored in .beads/embeddeddolt/.
  • By default, Dolt runs in embedded mode (in-process, no server needed).
  • For multi-writer setups, use bd init --server to connect to a dolt sql-server instead.
  • To import issues from an older installation, run bd init --from-jsonl.

​
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:
RoleUse caseIssue storage
maintainerRepo owner, team with push accessIn-repo .beads/
contributorFork contributor, OSS contributorSeparate 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.

​
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 (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)

​
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)
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)

​
Find ready work

bd ready
Output: 
Ready work (1 issues with no active 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.

​
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

​
Team sync

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. In repos with origin, bd init configures that Dolt remote automatically. 
# Verify the remote, or add one if the repo had no origin during init
bd dolt remote list
bd dolt remote add origin git+ssh://git@github.com/org/repo.git  # if needed

# 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, clones it, and wires origin for future bd dolt push / bd dolt pull. See bd dolt for CLI details. For remote configuration, see Dolt architecture; for federation, see federation.

​
Optional: Notion sync

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

​
Database location

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.

​
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 --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 recoverable via bd restore <id> (from the pre-compaction snapshot, with Dolt history as fallback).

​
Next steps

  • Add labels: bd create "Task" -l "backend,urgent"
  • Filter ready work: bd ready --priority 1
  • Explain the graph: bd ready --explain
  • Check graph integrity: bd graph check
  • Search issues: bd list --status open
  • Detect cycles: bd dep cycles
  • Gates for PR/CI sync: bd gate
  • More sync scenarios: bd dolt
  • Full command list: CLI Reference
See the repository README for an overview and links to deeper docs.