* docs: link canonical SYNC_CONCEPTS.md from deeper docs SYNC_CONCEPTS.md is the canonical cross-machine sync explainer but was only linked from README.md. Add a one-line pointer from ARCHITECTURE, DOLT, FAQ, GIT_INTEGRATION, and SYNC_SETUP so readers deep in those docs can find it. Docs-only; all pointers steer toward bd dolt push/pull as canonical sync. Salvages the still-relevant piece of #3726 (closed as superseded by #3909). Agent-Signature: claude-opus-4-8-medium on behalf of maphew * docs: dedupe duplicate DOLT.md entry in SYNC_SETUP See Also The See Also list had two DOLT.md links with different descriptions (pre-existing on main). Merge into a single entry. Agent-Signature: claude-opus-4-8-medium on behalf of maphew
515 lines
18 KiB
Markdown
515 lines
18 KiB
Markdown
# Frequently Asked Questions
|
|
|
|
Common questions about bd (beads) and how to use it effectively.
|
|
|
|
## General Questions
|
|
|
|
### What is bd?
|
|
|
|
bd is a lightweight, Dolt-powered issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, so agents and humans can collaborate from the same task graph.
|
|
|
|
### Why not just use GitHub Issues?
|
|
|
|
GitHub Issues + gh CLI can approximate some features, but fundamentally cannot replicate what AI agents need:
|
|
|
|
**Key Differentiators:**
|
|
|
|
1. **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
|
|
|
|
2. **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
|
|
|
|
3. **Offline-First, 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
|
|
|
|
4. **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
|
|
|
|
5. **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
|
|
|
|
6. **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, version-controlled task memory with graph semantics and deterministic queries.
|
|
|
|
See [GitHub issue #125](https://github.com/gastownhall/beads/issues/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
|
|
- **Built-in sync**: Version-controlled storage with native push/pull, no separate sync server to run
|
|
- **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: Active development with 1.x releases**
|
|
|
|
bd is in active development and being dogfooded on real projects. The core functionality (create, update, dependencies, ready work, Dolt-backed sync) is stable and well-tested. However:
|
|
|
|
- **CLI/API changes still happen** - command flags and data formats can evolve
|
|
- **Safe for development/internal projects** - use normal backup and sync hygiene
|
|
- **Data is portable** - `bd export` produces human-readable JSONL for 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 without a tested backup/restore plan
|
|
- Large enterprise deployments that need formal compatibility guarantees
|
|
- Long-term archival as the only system of record
|
|
|
|
Follow the repo for updates and compatibility notes.
|
|
|
|
## 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
bd init # Interactive - prompts for git hooks
|
|
```
|
|
|
|
**Agents:**
|
|
```bash
|
|
bd init --quiet # Non-interactive - auto-installs hooks, no prompts
|
|
```
|
|
|
|
**Workflow for humans:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bd init # Auto-configures git origin as the Dolt remote when present
|
|
# or: bd init --remote http://myserver:7007/mydb # Explicit non-origin remote
|
|
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.
|
|
|
|
For the full conceptual model — why the local Dolt database is the source of truth, what `issues.jsonl` is and is not for, and which sync patterns to avoid — see [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md).
|
|
|
|
### What if my database feels stale after a colleague pushes changes?
|
|
|
|
Pull from the Dolt remote:
|
|
|
|
```bash
|
|
bd dolt pull # Fetch and merge updates from Dolt remote
|
|
bd ready # Shows fresh data
|
|
```
|
|
|
|
For federation setups, use:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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/` automatically
|
|
- Agents in subdirectories - bd walks up to find the project root (like git)
|
|
- **Per-project Dolt servers** (default) - each project gets its own Dolt server
|
|
- **Shared Dolt server** (opt-in) - all projects share a single server for reduced resource usage
|
|
|
|
**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:
|
|
```bash
|
|
# 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):
|
|
```bash
|
|
# 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](DOLT.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> --claim`
|
|
- 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](DOLT.md) for detailed analysis.
|
|
|
|
### How do I handle merge conflicts?
|
|
|
|
When two developers create new issues:
|
|
|
|
```diff
|
|
{"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:
|
|
|
|
1. Export issues from your current tracker (usually CSV or JSON)
|
|
2. Write a simple script to convert to bd's JSONL format
|
|
3. Place the JSONL file at `.beads/issues.jsonl` and run `bd init --from-jsonl`
|
|
|
|
See [examples/](../examples/) for scripting patterns. Contributions welcome!
|
|
|
|
### Can I export back to GitHub Issues / Jira?
|
|
|
|
Not yet built-in, but you can:
|
|
|
|
1. Export from bd: `bd export -o issues.jsonl --json`
|
|
2. Write a script to convert JSONL to your target format
|
|
3. Use the target system's API to import
|
|
|
|
The [CONFIG.md](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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
|
|
1. Query ready work: `bd ready --assignee agent-name`
|
|
2. Assign issues: `bd update <id> --assignee agent-name`
|
|
3. Start work (as assigned agent): `bd update <id> --status in_progress`
|
|
4. Create discovered work: `bd create "Found issue" --deps discovered-from:<parent-id>`
|
|
5. Sync via `bd dolt push` / `bd dolt pull`
|
|
|
|
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 version-controlled storage means agents work independently and merge their changes like developers do, with cell-level merge resolving most conflicts automatically.
|
|
|
|
### 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 `bd dolt push` / `bd dolt 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](INSTALLING.md#windows-11) for details.
|
|
|
|
### Can I use bd with git worktrees?
|
|
|
|
Yes! Dolt handles worktrees natively. Use embedded mode if the Dolt server is not needed:
|
|
|
|
```bash
|
|
bd dolt set mode embedded
|
|
bd ready
|
|
bd create "Fix bug" -p 1
|
|
```
|
|
|
|
See [WORKTREES.md](WORKTREES.md) for details.
|
|
|
|
### Why did beads create worktrees in my .git directory?
|
|
|
|
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:
|
|
|
|
```bash
|
|
rm -rf .git/beads-worktrees
|
|
rm -rf .git/worktrees/beads-*
|
|
git worktree prune
|
|
```
|
|
|
|
**To disable sync-branch (stop worktree creation):**
|
|
|
|
```bash
|
|
bd config set sync.branch ""
|
|
```
|
|
|
|
See [WORKTREES.md#beads-created-worktrees-sync-branch](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:
|
|
```bash
|
|
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](../README.md), [QUICKSTART.md](QUICKSTART.md), [ADVANCED.md](ADVANCED.md)
|
|
- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
- **Examples**: [examples/](../examples/)
|
|
- **GitHub Issues**: [Report bugs or request features](https://github.com/gastownhall/beads/issues)
|
|
- **GitHub Discussions**: [Ask questions](https://github.com/gastownhall/beads/discussions)
|
|
|
|
### How can I contribute?
|
|
|
|
Contributions are welcome! See [CONTRIBUTING.md](../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:
|
|
|
|
```bash
|
|
bd list --priority 0 --priority 1 --json
|
|
```
|
|
|
|
Or check the GitHub Issues for feature requests and planned improvements.
|