docs/FAQ.md
Common questions about bd (beads) and how to use it effectively.
bd is a lightweight, git-based issue tracker designed for AI coding agents. It provides dependency-aware task management with automatic sync across machines via git.
GitHub Issues + gh CLI can approximate some features, but fundamentally cannot replicate what AI agents need:
Key Differentiators:
Typed Dependencies with Semantics
blocks, related, parent-child, discovered-from) with different behaviorsdiscovered-from for agent work discoveryDeterministic Ready-Work Detection
bd ready computes transitive blocking offline in ~10ms, no network requiredGit-First, Offline, Branch-Scoped Task Memory
AI-Resolvable Conflicts & Duplicate Merge
Version-Controlled SQL Database
Agent-Native APIs
--json on all commands, dedicated MCP server with auto workspace detectionWhen to use each: GitHub Issues excels for human teams in web UI with cross-repo dashboards and integrations. bd excels for AI agents needing offline, git-synchronized task memory with graph semantics and deterministic queries.
See GitHub issue #125 for detailed comparison.
Taskwarrior is excellent for personal task management, but bd is built for AI agents:
discovered-from dependency type, bd ready for queue management--json outputAbsolutely! bd is a great CLI issue tracker for humans too. The bd ready command is useful for anyone managing dependencies. Think of it as "Taskwarrior meets git."
Current status: Alpha (v0.9.11)
bd is in active development and being dogfooded on real projects. The core functionality (create, update, dependencies, ready work, collision resolution) is stable and well-tested. However:
bd export produces human-readable JSONL for easy migrationWhen to use bd:
When to wait:
bd export makes migration easy)Follow the repo for updates and the path to 1.0!
Hash IDs eliminate collisions when multiple agents or branches create issues concurrently.
The problem with sequential IDs:
# Branch A creates bd-10
git checkout -b feature-auth
bd create "Add OAuth" # Sequential ID: bd-10
# Branch B also creates bd-10
git checkout -b feature-payments
bd create "Add Stripe" # Collision! Same sequential ID: bd-10
# Merge conflict!
git merge feature-auth # Two different issues, same ID
Hash IDs solve this:
# Branch A
bd create "Add OAuth" # Hash ID: bd-a1b2 (from random UUID)
# Branch B
bd create "Add Stripe" # Hash ID: bd-f14c (different UUID, different hash)
# Clean merge!
git merge feature-auth # No collision, different IDs
Progressive length scaling:
bd-a1b2bd-f14c3bd-3e7a5bbd automatically extends hash length as your database grows to maintain low collision probability.
Hierarchical IDs (e.g., bd-a3f8e9.1, bd-a3f8e9.2) provide human-readable structure for epics and their subtasks.
Example:
# Create epic (generates parent hash)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create children (auto-numbered .1, .2, .3)
bd create "Login UI" -p 1 # bd-a3f8e9.1
bd create "Validation" -p 1 # bd-a3f8e9.2
bd create "Tests" -p 1 # bd-a3f8e9.3
Benefits:
When to use:
When NOT to use:
bd dep add instead)Either works! But use the right flag:
Humans:
bd init # Interactive - prompts for git hooks
Agents:
bd init --quiet # Non-interactive - auto-installs hooks, no prompts
Workflow for humans:
# Clone existing project with bd:
git clone <repo>
cd <repo>
bd init # Creates Dolt database, pulls from remote if configured
# Or initialize new project:
cd ~/my-project
bd init # Creates .beads/, sets up Dolt database
git add .beads/
git commit -m "Initialize beads"
Workflow for agents setting up repos:
git clone <repo>
cd <repo>
bd init --quiet # No prompts, auto-installs hooks
bd ready --json # Start using bd normally
No! Dolt handles storage and versioning natively.
All writes go directly to the Dolt database and are automatically committed to Dolt history. To sync with Dolt remotes:
bd dolt push # Push changes to Dolt remote
bd dolt pull # Pull changes from Dolt remote
The bd export command exists for issue portability and interchange. For backup and restore, use bd backup init <path> / bd backup sync to push Dolt-native backups, and bd backup restore <path> to restore from them. None of these are needed for day-to-day Dolt sync.
Pull from the Dolt remote:
bd dolt pull # Fetch and merge updates from Dolt remote
bd ready # Shows fresh data
For federation setups, use:
bd federation sync # Sync with all configured peers
Yes! Each project is completely isolated. bd uses project-local databases:
cd ~/project1 && bd init --prefix proj1
cd ~/project2 && bd init --prefix proj2
Each project gets its own .beads/ directory with its own Dolt database. bd auto-discovers the correct database based on your current directory (walks up like git).
Multi-project scenarios work seamlessly:
.beads/ automaticallyLimitation: Issues cannot reference issues in other projects. Each database is isolated by design. If you need cross-project tracking, initialize bd in a parent directory that contains both projects.
Example: Multiple agents, multiple projects, same machine:
# Agent 1 working on web app
cd ~/work/webapp && bd ready --json # Uses ~/work/webapp/.beads/ database "webapp"
# Agent 2 working on API
cd ~/work/api && bd ready --json # Uses ~/work/api/.beads/ database "api"
# No conflicts! Completely isolated databases.
Shared server mode (recommended for machines with 2+ projects):
# Enable shared server - single Dolt process serves all projects
export BEADS_DOLT_SHARED_SERVER=1 # add to shell profile for machine-wide
# Or per-project: bd dolt set shared-server true
Architecture: By default, bd uses per-project Dolt servers (like LSP/language servers). With shared server mode enabled, a single server at ~/.beads/shared-server/ handles all projects, each using its own database. See DOLT.md for details.
With Dolt server mode, concurrent writes are handled natively. For distributed setups, Dolt's cell-level merge resolves most conflicts automatically. To prevent conflicts:
bd update <id> --claimbd ready --assignee agent-nameFor true multi-agent coordination, use Dolt server mode (bd dolt start) which supports concurrent writes natively. For distributed setups, use Dolt federation for peer-to-peer sync.
bd export produces JSONL for migration and interoperabilitySee DOLT.md for detailed analysis.
When two developers create new issues:
{"id":"bd-1","title":"First issue",...}
{"id":"bd-2","title":"Second issue",...}
+{"id":"bd-3","title":"From branch A",...}
+{"id":"bd-4","title":"From branch B",...}
Git may show a conflict, but resolution is simple: keep both lines (both changes are compatible).
With hash-based IDs (v0.20.1+), same-ID scenarios are updates, not collisions:
If you import an issue with the same ID but different fields, bd treats it as an update to the existing issue. This is normal behavior - hash IDs remain stable, so same ID = same issue being updated.
Dolt handles merge conflicts natively with cell-level merge. Use bd vc conflicts to view and resolve any conflicts after pulling.
We don't have automated migration tools yet, but you can:
.beads/issues.jsonl and run bd init --from-jsonlSee examples/ for scripting patterns. Contributions welcome!
Not yet built-in, but you can:
bd export -o issues.jsonl --jsonThe CONFIG.md guide shows how to store integration settings. Contributions for standard exporters welcome!
bd uses Dolt (a version-controlled SQL database), which handles millions of rows efficiently. For a typical project with thousands of issues:
For extremely large projects (100k+ issues), you might want to filter exports or use multiple databases per component.
Use compaction to remove old closed issues:
# Preview what would be compacted
bd admin compact --dry-run --all
# Compact issues closed more than 90 days ago
bd admin compact --days 90
# Run Dolt garbage collection
cd .beads/dolt && dolt gc
Or split your project into multiple databases:
cd ~/project/frontend && bd init --prefix fe
cd ~/project/backend && bd init --prefix be
Sure! bd is just an issue tracker. Use it for:
The agent-friendly design works for any AI-assisted workflow.
Yes! Each agent can:
bd ready --assignee agent-namebd update <id> --assignee agent-namebd update <id> --status in_progressbd create "Found issue" --deps discovered-from:<parent-id>Note: In orchestrated workflows, assignment is usually done by an orchestrator.
If the issue is already assigned, start with bd update <id> --status in_progress.
If an agent picks work directly, use atomic bd update <id> --claim --assignee agent-name.
bd's git-based sync means agents work independently and merge their changes like developers do.
Yes! bd is designed for offline-first operation:
This makes bd ideal for:
bd is a single static binary with no runtime dependencies:
That's it! No PostgreSQL, no Redis, no Docker, no node_modules.
With the Dolt backend, use bd query for direct SQL access or build integrations using bd --json CLI output.
Yes! bd has native Windows support (v0.9.0+):
See INSTALLING.md for details.
Yes! Dolt handles worktrees natively. Use embedded mode if the Dolt server is not needed:
bd dolt set mode embedded
bd ready
bd create "Fix bug" -p 1
See WORKTREES.md for details.
Older versions of beads created git worktrees for a sync-branch feature that has since been removed. Dolt now stores data under refs/dolt/data, separate from standard Git refs, so a separate branch is no longer needed.
If you have leftover worktrees from an older version, you can safely remove them:
rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune
To disable sync-branch (stop worktree creation):
bd config set sync.branch ""
See WORKTREES.md#beads-created-worktrees-sync-branch for full details.
bd handles two distinct types of integrity issues:
1. Logical Consistency (Collision Resolution)
The hash/fingerprint/collision architecture prevents:
Solution: Hash-based IDs (v0.20+) eliminate collisions. Different issues automatically get different IDs.
2. Physical Database Corruption
Database corruption can occur from:
Solution: Rebuild from Dolt remote or a backup export:
rm -rf .beads/dolt
bd init
bd dolt pull # Pull from Dolt remote if configured
Key Difference: Collision resolution fixes logical issues in the data. Physical corruption requires restoring from Dolt remotes or backup exports.
For multi-writer scenarios: Use Dolt server mode (bd dolt set mode server) to allow concurrent access from multiple processes.
Contributions are welcome! See CONTRIBUTING.md for:
The roadmap lives in bd itself! Run:
bd list --priority 0 --priority 1 --json
Or check the GitHub Issues for feature requests and planned improvements.