beads/FAQ.md

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:

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. Git-First, Offline, Branch-Scoped Task Memory

   • bd: Works offline, issues live on branches, mergeable with code via bd import --resolve-collisions
   • 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. Extensible Local Database

   • bd: Add SQL tables and join with issue data locally (see EXTENDING.md)
   • 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, 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
• Merge-friendly JSONL: One issue per line, AI-resolvable conflicts
• Extensible SQLite: Add your own tables without forking

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 JSONL format may evolve before 1.0
• ✅ Safe for development - Use for development/internal projects
• ✅ Data is portable - JSONL format is human-readable and easy to migrate
• 📈 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 JSONL makes migration easy)

Follow the repo for updates and the path to 1.0!

Usage Questions

Do I need to run export/import manually?

No! Sync is automatic by default.

bd automatically:

• Exports to JSONL after CRUD operations (5-second debounce)
• Imports from JSONL when it's newer than DB (after git pull)

Optional: For immediate export (no 5-second wait) and guaranteed import after git operations, install the git hooks:

cd examples/git-hooks && ./install.sh

Disable auto-sync if needed:

bd --no-auto-flush create "Issue"   # Disable auto-export
bd --no-auto-import list            # Disable auto-import

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 database and JSONL file. 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)
• Global daemon → One daemon process serves all projects (v0.9.11+)

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.

Recommended for multi-project setups: Use the global daemon (bd daemon --global) to serve all projects with a single daemon process. See ADVANCED.md#global-daemon-for-multiple-projects.

What happens if two agents work on the same issue?

The last agent to export/commit wins. This is the same as any git-based workflow. 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, you'd need additional tooling (like locks or a coordination server). bd handles the simpler case: multiple humans/agents working on different tasks, syncing via git.

Why JSONL instead of JSON?

• ✅ Git-friendly: One line per issue = clean diffs
• ✅ Mergeable: Concurrent appends rarely conflict
• ✅ Human-readable: Easy to review changes
• ✅ Scriptable: Use jq, grep, or any text tools
• ✅ Portable: Export/import between databases

See TEXT_FORMATS.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).

For ID collisions (same ID, different content):

bd import -i .beads/issues.jsonl --resolve-collisions

See ADVANCED.md#handling-import-collisions for details.

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

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 guide shows how to store integration settings. Contributions for standard exporters welcome!

Performance Questions

How does bd handle scale?

bd uses SQLite, 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
• JSONL files stay small (one line per issue)

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

What if my JSONL file gets too large?

Use compaction to remove old closed issues:

# Preview what would be compacted
bd compact --dry-run --all

# Compact issues closed more than 90 days ago
bd compact --days 90

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:

1. Query ready work: bd ready --assignee agent-name
2. Claim issues: bd update <id> --status in_progress --assignee agent-name
3. Create discovered work: bd create "Found issue" --deps discovered-from:<parent-id>
4. 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 SQLite 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: SQLite (embedded, pure Go driver)
• Optional: Git (for sync across machines)

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

Can I extend bd's database?

Yes! See EXTENDING.md for how to:

• Add custom tables to the SQLite database
• Join with issue data
• Build custom queries
• Create integrations

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
• Daemon uses TCP instead of Unix sockets

See INSTALLING.md for details.

Can I use bd with git worktrees?

Yes, but with limitations. The daemon doesn't work correctly with worktrees, so use --no-daemon mode:

export BEADS_NO_DAEMON=1
bd ready
bd create "Fix bug" -p 1

See ADVANCED.md#git-worktrees for details.

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.