--- title: Quick Start description: Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes --- 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:** ```bash $ 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](/getting-started/installation) (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`. ```bash bd --help ``` ## Initialize First time in a repository: ```bash # 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: | 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: ```bash # 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 ```bash # 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: ```bash # 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) ``` Children inherit the epic's labels by default — if the epic carries a size/effort label, see [Labels](/core-concepts/labels) for how to keep it off the children. ## Add dependencies ```bash # 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 ```bash 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: ```bash 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 ```bash # 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 ```bash # 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. ```bash # 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`](/cli-reference/dolt) for CLI details. For remote configuration, see [Dolt architecture](/architecture/dolt); for federation, see [federation](/multi-agent/federation). ## Optional: Notion sync If you keep project issues in Notion, supply an integration token first: ```bash export NOTION_TOKEN= # or, if .beads/config.yaml is not tracked by git: bd config set notion.token ``` `bd config set` never writes the token to the Dolt database, so `bd dolt push` does not send it to a remote. It writes the token to `.beads/config.yaml` instead, and refuses when that file is tracked by git, as it is after `bd init` in a git repository. Then either create a new Beads database under a parent page or connect to an existing target: ```bash bd notion init --parent # or bd notion connect --url ``` 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: ```bash bd notion status bd notion status --json ``` Preview or run sync: ```bash 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, check for pending database migrations and apply them: ```bash # Inspect migration plan (AI agents) bd migrate --inspect --json # Check schema and config bd info --schema --json # Preview migration changes bd migrate --dry-run # Apply pending schema migrations bd migrate schema # 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: ```bash # 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 ` (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`](/cli-reference/gate) - More sync scenarios: [`bd dolt`](/cli-reference/dolt) - Full command list: [CLI Reference](/cli-reference/index) See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.