Frequently Asked Questions

Common questions about bd (beads) and how to use it effectively.

General Questions

What is bd?

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.

Why not just use GitHub Issues?

GitHub Issues + gh CLI can approximate some features, but fundamentally cannot replicate what AI agents need:

Key Differentiators:

Typed Dependencies with Semantics
- bd: Four types (blocks, related, parent-child, discovered-from) with different behaviors
- GH: Only "blocks/blocked by" links, no semantic enforcement, no discovered-from for agent work discovery
Deterministic Ready-Work Detection
- bd: bd ready computes transitive blocking offline in ~10ms, no network required
- GH: No built-in "ready" concept; would require custom GraphQL + sync service + ongoing maintenance
Git-First, Offline, Branch-Scoped Task Memory
- bd: Works offline, issues live on branches, hash IDs prevent collisions on merge
- GH: Cloud-first, requires network/auth, global per-repo, no branch-scoped task state
AI-Resolvable Conflicts & Duplicate Merge
- bd: Automatic collision resolution, duplicate merge with dependency consolidation and reference rewriting
- GH: Manual close-as-duplicate, no safe bulk merge, no cross-reference updates
Version-Controlled SQL Database
- bd: Full SQL queries against local Dolt database with native version control
- GH: No local database; would need to mirror data externally
Agent-Native APIs
- bd: Consistent --json on all commands, dedicated MCP server with auto workspace detection
- GH: Mixed JSON/text output, GraphQL requires custom queries, no agent-focused MCP layer

When 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.

How is this different from Taskwarrior?

Taskwarrior is excellent for personal task management, but bd is built for AI agents:

Explicit agent semantics: discovered-from dependency type, bd ready for queue management
JSON-first design: Every command has --json output
Git-native sync: No sync server setup required
Dolt merge: Cell-level merge with AI-resolvable conflicts
SQL database: Full SQL queries against Dolt database

Can I use bd without AI agents?

Absolutely! 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."

Is this production-ready?

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:

⚠️ Alpha software - No 1.0 release yet
⚠️ API may change - Command flags and data format may evolve before 1.0
✅ Safe for development - Use for development/internal projects
✅ Data is portable - bd export produces human-readable JSONL for easy migration
📈 Rapid iteration - Expect frequent updates and improvements

When to use bd:

✅ AI-assisted development workflows
✅ Internal team projects
✅ Personal productivity with dependency tracking
✅ Experimenting with agent-first tools

When to wait:

❌ Mission-critical production systems (wait for 1.0)
❌ Large enterprise deployments (wait for stability guarantees)
❌ Long-term archival (though bd export makes migration easy)

Follow the repo for updates and the path to 1.0!

Usage Questions

Why hash-based IDs? Why not sequential?

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:

4 chars (0-500 issues): bd-a1b2
5 chars (500-1,500 issues): bd-f14c3
6 chars (1,500+ issues): bd-3e7a5b

bd automatically extends hash length as your database grows to maintain low collision probability.

What are hierarchical child IDs?

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:

Parent hash ensures unique namespace (no cross-epic collisions)
Sequential child IDs are human-friendly
Up to 3 levels of nesting supported
Clear visual grouping in issue lists

When to use:

Epics with multiple related tasks
Large features with sub-features
Work breakdown structures

When NOT to use:

Simple one-off tasks (use regular hash IDs)
Cross-cutting dependencies (use bd dep add instead)

Should I run bd init or have my agent do it?

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

Do I need to run export/import manually?

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 import and bd export commands exist for data migration and portability (e.g., bootstrapping new clones, backing up data), not for day-to-day sync.

What if my database feels stale after a colleague pushes changes?

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

Can I track issues for multiple projects?

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:

Multiple agents working on different projects simultaneously → No conflicts
Same machine, different repos → Each finds its own .beads/*.db automatically
Agents in subdirectories → bd walks up to find the project root (like git)
Per-project Dolt servers → Each project gets its own Dolt server (LSP model)

Limitation: 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/webapp.db

# Agent 2 working on API
cd ~/work/api && bd ready --json       # Uses ~/work/api/.beads/api.db

# No conflicts! Completely isolated databases and Dolt servers.

Architecture: bd uses per-project Dolt servers (like LSP/language servers) for complete database isolation. See ADVANCED.md for details.

What happens if two agents work on the same issue?

With Dolt server mode, concurrent writes are handled natively. For distributed setups, Dolt's cell-level merge resolves most conflicts automatically. To prevent conflicts:

Have agents claim work with bd update <id> --status in_progress
Query by assignee: bd ready --assignee agent-name
Review git diffs before merging

For 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.

Why Dolt instead of plain files?

✅ Version-controlled SQL: Full SQL queries with native version control
✅ Cell-level merge: Concurrent changes merge automatically at the field level
✅ Multi-writer: Server mode supports concurrent agents
✅ Native branching: Dolt branches independent of git branches
✅ Portable: bd export produces JSONL for migration and interoperability

See DOLT.md for detailed analysis.

How do I handle merge conflicts?

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.

Migration Questions

How do I migrate from GitHub Issues / Jira / Linear?

We don't have automated migration tools yet, but you can:

Export issues from your current tracker (usually CSV or JSON)
Write a simple script to convert to bd's JSONL format
Import with bd import -i issues.jsonl

See examples/ for scripting patterns. Contributions welcome!

Can I export back to GitHub Issues / Jira?

Not yet built-in, but you can:

Export from bd: bd export -o issues.jsonl --json
Write a script to convert JSONL to your target format
Use the target system's API to import

The CONFIG.md guide shows how to store integration settings. Contributions for standard exporters welcome!

Performance Questions

How does bd handle scale?

bd uses Dolt (a version-controlled SQL database), which handles millions of rows efficiently. For a typical project with thousands of issues:

Commands complete in <100ms
Full-text search is instant
Dependency graphs traverse quickly
Dolt database stays compact with garbage collection

For extremely large projects (100k+ issues), you might want to filter exports or use multiple databases per component.

What if my database gets too large?

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

Use Case Questions

Can I use bd for non-code projects?

Sure! bd is just an issue tracker. Use it for:

Writing projects (chapters as issues, dependencies as outlines)
Research projects (papers, experiments, dependencies)
Home projects (renovations with blocking tasks)
Any workflow with dependencies

The agent-friendly design works for any AI-assisted workflow.

Can I use bd with multiple AI agents simultaneously?

Yes! Each agent can:

Query ready work: bd ready --assignee agent-name
Claim issues: bd update <id> --status in_progress --assignee agent-name
Create discovered work: bd create "Found issue" --deps discovered-from:<parent-id>
Sync via git commits

bd's git-based sync means agents work independently and merge their changes like developers do.

Does bd work offline?

Yes! bd is designed for offline-first operation:

All queries run against local Dolt database
No network required for any commands
Sync happens via git push/pull when you're online
Full functionality available without internet

This makes bd ideal for:

Working on planes/trains
Unstable network connections
Air-gapped environments
Privacy-sensitive projects

Technical Questions

What dependencies does bd have?

bd is a single static binary with no runtime dependencies:

Language: Go 1.24+
Database: Dolt (server mode)
Optional: Git (for version control of project code)

That's it! No PostgreSQL, no Redis, no Docker, no node_modules.

Can I extend bd's database?

With the Dolt backend, use bd query for direct SQL access or build integrations using bd --json CLI output.

Does bd support Windows?

Yes! bd has native Windows support (v0.9.0+):

No MSYS or MinGW required
PowerShell install script
Works with Windows paths and filesystem
Dolt server uses TCP instead of Unix sockets

See INSTALLING.md for details.

Can I use bd with git worktrees?

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.

Why did beads create worktrees in my .git directory?

Beads automatically creates git worktrees when using the sync-branch feature. This happens when you:

Run bd init --branch <name>
Set bd config set sync.branch <name>

The worktrees allow beads to commit issue updates to a separate branch without switching your working directory.

Location: .git/beads-worktrees/<sync-branch>/

Common issue: If you see "branch already checked out" errors when switching branches, remove the beads worktrees:

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.

What's the difference between database corruption and ID collisions?

bd handles two distinct types of integrity issues:

1. Logical Consistency (Collision Resolution)

The hash/fingerprint/collision architecture prevents:

ID collisions: Same ID assigned to different issues (e.g., from parallel workers or branch merges)
Wrong prefix bugs: Issues created with incorrect prefix due to config mismatch
Merge conflicts: Branch divergence creating conflicting data

Solution: Hash-based IDs (v0.20+) eliminate collisions. Different issues automatically get different IDs.

2. Physical Database Corruption

Database corruption can occur from:

Disk/hardware failures: Power loss, disk errors, filesystem corruption
Concurrent writes: Multiple processes writing to the database simultaneously

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.

Getting Help

Where can I get more help?

Documentation: README.md, QUICKSTART.md, ADVANCED.md
Troubleshooting: TROUBLESHOOTING.md
Examples: examples/
GitHub Issues: Report bugs or request features
GitHub Discussions: Ask questions

How can I contribute?

Contributions are welcome! See CONTRIBUTING.md for:

Code contribution guidelines
How to run tests
Development workflow
Issue and PR templates

Where's the roadmap?

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.

FilesExpand file tree

FAQ.md

Latest commit

History