FAQ - Beads Documentation

General

What is beads?

Beads (bd) is a lightweight, Dolt-backed 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. See Core Concepts for the full model.

Why beads instead of GitHub Issues or Jira?

GitHub Issues plus the gh CLI can approximate some features, but hosted trackers fundamentally cannot replicate what AI agents need:

Capability	beads	GitHub Issues
Typed dependencies	Core types (`blocks`, `related`, `parent-child`, `discovered-from`) plus workflow and knowledge-graph edges	Only “blocks/blocked by” links; no semantic enforcement, no `discovered-from` for agent work discovery
Ready-work detection	`bd ready` computes transitive blocking offline in milliseconds	No built-in “ready” concept; requires custom GraphQL plus a sync service
Offline-first task memory	Works offline; issues live in a local, version-controlled database; hash IDs prevent collisions on merge	Cloud-first; requires network and auth; no branch-scoped task state
Conflicts and duplicates	Automatic collision resolution; duplicate merge with dependency consolidation and reference rewriting	Manual close-as-duplicate; no safe bulk merge, no cross-reference updates
Local SQL database	Full SQL queries against a local Dolt database with native version control	No local database; data must be mirrored externally
Agent-native APIs	Consistent `--json` on all commands; dedicated MCP server with workspace detection	Mixed JSON/text output; no agent-focused MCP layer

When to use each: GitHub Issues and Jira excel for human teams working in a web UI with cross-repo dashboards and integrations. Beads excels for AI agents that need offline, version-controlled task memory with graph semantics and deterministic queries. The two can also coexist — beads syncs bidirectionally with GitHub, Jira, and Linear (see Migration).

How is beads different from Taskwarrior?

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

Agent semantics: the 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
Cell-level merge: concurrent changes merge automatically at the field level
SQL database: full SQL queries against the Dolt database

Can I use beads without AI agents?

Absolutely. Beads is a good CLI issue tracker for humans too — bd ready is useful for anyone managing dependencies. Think of it as “Taskwarrior meets git.”

What does “beads” stand for?

Nothing specific — it’s a metaphor for linked work items, like beads on a string.

Is beads production-ready?

Beads is a 1.x product used in production for AI-assisted development. The core functionality — create, update, dependencies, ready work, Dolt-backed sync — is stable, and releases follow semantic versioning. Data stays portable: bd export produces human-readable JSONL, and bd backup pushes Dolt-native backups. As with any tracker holding work you care about, keep normal backup hygiene (a Dolt remote or a bd backup destination).

Architecture

Why Dolt instead of plain SQLite or flat files?

Dolt is a version-controlled SQL database — git semantics at the database level:

Version-controlled SQL: full SQL queries with branch, diff, and merge built in
Cell-level merge: concurrent changes merge automatically at the field level
No separate sync format: bd dolt push / bd dolt pull move history natively
Multi-writer: server mode supports concurrent agents
Portable: bd export produces JSONL for migration and interoperability

See Dolt architecture for the detailed analysis.

Why hash-based IDs instead of sequential?

Sequential IDs (#1, #2) collide the moment two agents or two branches create issues concurrently — both mint the same next number, and the merge produces two different issues with one ID. Hash IDs like bd-a1b2 are globally unique without coordination:

# Branch A
bd create "Add OAuth"   # bd-a1b2

# Branch B
bd create "Add Stripe"  # bd-f14c — no collision

git merge feature-auth  # clean merge, distinct IDs

IDs start at 3 characters and grow automatically (up to 8) as the database grows, keeping the collision probability under a fixed threshold. See Hash IDs and Adaptive IDs, or the collision math if you want the numbers.

What are hierarchical child IDs?

Hierarchical IDs (bd-a3f8e9.1, bd-a3f8e9.2) give epics and their subtasks human-readable structure:

bd create "Auth System" -t epic          # bd-a3f8e9
bd create "Login UI" --parent bd-a3f8e9  # bd-a3f8e9.1
bd create "Validation" --parent bd-a3f8e9 # bd-a3f8e9.2

The parent hash keeps the namespace unique across epics, the child numbers stay human-friendly, and up to 3 levels of nesting are supported. Use them for work breakdown structures; for cross-cutting relationships, use bd dep add instead. See Hash IDs.

Embedded mode or server mode — which am I running?

The default bd init uses embedded mode: Dolt runs in-process inside bd, data lives at .beads/embeddeddolt/, and there is no server, port, or PID file to manage. This is the right mode for solo work, CI/CD, and single-agent setups. Server mode (bd init --server) connects to a running dolt sql-server and stores data at .beads/dolt/. Switch to it when multiple processes need concurrent write access to the same database — for example several agents on one machine. See Dolt architecture for setup and migration between modes.

Usage

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

Either works — use the right flag:

bd init          # Humans: interactive, prompts for git hooks
bd init --quiet  # Agents: non-interactive, auto-installs hooks

For an existing project, clone and run bd init; it creates the Dolt database and pulls from the configured remote. For a new project, run bd init, then commit the .beads/ directory.

How do I sync issues across machines?

bd dolt push    # Push changes to the Dolt remote
bd dolt pull    # Pull changes from the Dolt remote

bd init auto-configures your git origin as the Dolt remote when present; use bd init --remote <url> for an explicit remote. See Sync Setup.

Do I need to run export/import manually?

No. All writes go directly to the Dolt database and are committed to Dolt history automatically; bd dolt push / bd dolt pull handle sync. bd export exists for portability and interchange — .beads/issues.jsonl is a passive export, never the database. For backups, use bd backup init <path> / bd backup sync / bd backup restore. See Sync Concepts for the full model and the sync patterns to avoid.

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

bd dolt pull    # Fetch and merge updates from the Dolt remote
bd ready        # Shows fresh data

For federation setups, bd federation sync syncs with all configured peers. See Federation.

How do I handle merge conflicts?

Dolt merges at the cell level, so most concurrent changes resolve automatically. Importing an issue with the same ID but different fields is an update, not a collision — hash IDs are stable, so same ID means same issue. If bd dolt pull does report conflicts:

bd doctor --fix
bd dolt push

See the merge conflicts runbook.

Can I track issues for multiple projects?

Yes — each project is completely isolated:

cd ~/project1 && bd init --prefix proj1
cd ~/project2 && bd init --prefix proj2

Each project gets its own .beads/ directory and database, and bd auto-discovers the right one by walking up from your current directory (like git). To link work across projects, hydrate the other repo into your database (bd repo add, then bd repo sync) and add normal dependencies, or depend on another project’s capability with an external:<project>:<capability> target — see cross-repo routing. In server mode, each project runs its own Dolt server by default. On machines with many projects you can opt into a single shared server (bd init --shared-server, or export BEADS_DOLT_SHARED_SERVER=1) that serves every project from ~/.beads/shared-server/. See Dolt architecture.

Can multiple agents work on the same repo?

Yes — that’s what beads was designed for. Hash IDs prevent collisions, and assignment tracks who’s working on what:

bd ready --assignee agent-name       # Query ready work for an agent
bd update bd-a1b2 --claim            # Atomically claim an issue (assignee + in_progress)
bd create "Found issue" --deps discovered-from:bd-a1b2   # Track discovered work

In orchestrated workflows an orchestrator usually assigns work (bd assign); agents picking work directly should use the atomic --claim. For multiple concurrent processes on one machine, use server mode; for distributed setups, Dolt’s cell-level merge and federation let agents work independently and merge like developers do. See Agent Coordination.

Does beads work offline?

Yes — beads is offline-first. All queries run against the local Dolt database, no command needs the network, and sync happens via bd dolt push / bd dolt pull when you’re online. That makes it suitable for planes, unstable connections, air-gapped environments, and privacy-sensitive projects.

How do I use beads in CI/CD?

Just run commands — embedded mode is the default, so no server is required:

bd list --json
bd ready --json

Workflows

What are formulas?

Declarative workflow templates in TOML or JSON. bd cook compiles a formula into a proto (a template epic), and bd mol pour instantiates the proto as a molecule of real, tracked beads. See Formulas.

What are gates?

Async coordination primitives that block a workflow step until a condition clears:

Human gates wait for approval
Timer gates wait for a duration
GitHub gates wait for CI runs or PR events

See Gates.

What’s the difference between molecules and wisps?

Both are instantiated workflows made of real beads. Molecules (bd mol pour) are persistent — part of history, synced like any bead. Wisps (bd mol wisp) are ephemeral — flagged so they stay out of federation push and can be deleted wholesale (bd purge, bd mol wisp gc) once closed. Use molecules for work worth referencing later, wisps for operational loops like release checklists and health patrols. See Molecules and Wisps.

Integrations

Should I use the CLI or MCP?

Use CLI + hooks when a shell is available (Claude Code, Cursor, and similar):

Lower context overhead (on the order of a couple thousand tokens, versus tens of thousands for a full set of MCP tool schemas)
Faster execution
Universal across editors

Use MCP when the CLI is unavailable (for example Claude Desktop). See MCP Server.

How do I integrate with my editor?

bd setup claude   # Claude Code
bd setup cursor   # Cursor
bd setup aider    # Aider

bd setup also supports copilot, gemini, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. See IDE Setup and the integrations index.

Can beads import from GitHub Issues?

Yes — bd github sync --pull-only imports issues in bulk (bd github pull <refs> cherry-picks specific ones), and bd github sync keeps beads and GitHub in sync bidirectionally. See the bd github reference.

Migration

How do I migrate from GitHub Issues, Jira, or Linear?

Beads has built-in bidirectional sync for all three — bd github, bd jira, and bd linear each provide sync for bulk moves, plus pull/push for specific issues by ID (GitLab, Azure DevOps, and Notion are covered by bd gitlab, bd ado, and bd notion). Configure credentials with bd config set per the CLI reference, then run the sync in the pull direction: bd github sync --pull-only, bd jira sync --pull, or bd linear sync --pull. For any other tracker: export from it (usually CSV or JSON), convert to beads’ JSONL format, and run bd import <file>. See examples for scripting patterns.

Can I export back out of beads?

For GitHub, Jira, and Linear, use the same integrations in the push direction — bd github sync --push-only, bd jira sync --push, or bd linear sync --push for everything, or bd <tracker> push <ids> for specific beads. For anything else, bd export -o issues.jsonl produces JSONL you can convert with a script and feed to the target system’s API.

Performance

How does beads handle scale?

Dolt is a SQL database and comfortably handles far more issues than a typical project accumulates. Commands stay fast at the thousands-of-issues scale; for extremely large projects (100k+ issues), consider splitting into multiple databases per component.

What if my database gets too large?

bd gc runs the full lifecycle: deletes old closed issues, squashes old Dolt commits, and runs Dolt garbage collection to reclaim disk space.

bd gc --dry-run          # Preview all phases
bd gc                    # Delete issues closed 90+ days ago, compact, GC
bd gc --older-than 30    # More aggressive decay window

For semantic summarization of old closed issues instead of deletion, see bd admin compact. Or split the project:

cd ~/project/frontend && bd init --prefix fe
cd ~/project/backend && bd init --prefix be

Use Cases

Can I use beads for non-code projects?

Sure — beads is just an issue tracker. Writing projects (chapters as issues, outlines as dependencies), research (papers, experiments), home projects (renovations with blocking tasks) — any workflow with dependencies works, and the agent-friendly design fits any AI-assisted workflow.

Technical

What dependencies does beads have?

Beads is a single static binary with no runtime dependencies — the Dolt engine is embedded in-process. No PostgreSQL, no Redis, no Docker, no node_modules. The standalone dolt CLI is only needed if you run server mode, and git is only needed to version your project code. See Installation.

Can I query or extend the database directly?

Yes, three ways: bd query for the built-in query language (compound filters, boolean operators, date expressions), bd sql for raw SQL against the underlying database, and --json output on every command for building integrations.

Does beads support Windows?

Yes — native Windows support, no MSYS or MinGW required. A PowerShell script installs prebuilt releases, and everything works with Windows paths. See Installation. Because bd.exe is a native binary, two integration details catch people out: Node programs cannot spawn the npm bd.cmd shim without a shell, and /tmp paths that reach bd unconverted — from Node, scripts, or config values — resolve to the drive root, not Git Bash’s /tmp. Both are covered under Platform-Specific Issues.

Can I use beads with git worktrees?

Yes — beads works from normal git worktrees with no special setup. All worktrees in a repository share the same .beads workspace; bd discovers it from linked worktrees automatically. If an old beads version left hidden worktrees under .git/ (from a since-removed sync-branch feature), clean them up:

rm -rf .git/beads-worktrees
rm -rf .git/worktrees/beads-*
git worktree prune

See Worktrees for details and legacy cleanup.

Troubleshooting

Why is the Dolt server not starting?

This applies to server mode only (embedded mode has no server):

bd doctor                        # Check health
cat .beads/dolt-server.log       # Check server logs (server mode)
bd dolt stop && bd dolt start    # Restart the server

See Troubleshooting.

Why aren’t my changes syncing?

bd dolt push     # Push to the Dolt remote
bd hooks list    # Verify git hooks are installed
bd doctor        # Check for deeper issues

See the sync failures runbook.

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

These are two distinct integrity issues: Logical consistency — same ID assigned to different issues, wrong-prefix bugs, branch divergence. Hash-based IDs eliminate collisions by design, and bd doctor --fix repairs logical inconsistencies. Physical corruption — disk failures, power loss, or multiple processes writing to an embedded database simultaneously. Start with the database corruption runbook (bd doctor --fix after backing up .beads/). If the database is unrecoverable and you have a Dolt remote, back up .beads/, delete the data directory for your mode — .beads/embeddeddolt/ in embedded mode, .beads/dolt/ in server mode — then re-init and pull:

cp -r .beads .beads.backup
rm -rf .beads/embeddeddolt   # or .beads/dolt in server mode
bd init
bd dolt pull

For multi-writer scenarios, use server mode so concurrent access goes through the server instead of racing on files.

How do I report a bug?

Check existing issues: https://github.com/gastownhall/beads/issues
Include bd version, bd info --json, and reproduction steps
File at: https://github.com/gastownhall/beads/issues/new

Getting Help

Where can I get more help?

Documentation: Quickstart, Advanced Features, README
Troubleshooting: Troubleshooting guide and the recovery runbooks
Examples: examples/
GitHub Issues: Report bugs or request features
GitHub Discussions: Ask questions

How can I contribute?

Contributions are welcome. See CONTRIBUTING.md for guidelines, test instructions, and the development workflow.

Where’s the roadmap?

The roadmap lives in beads itself:

bd list --priority-max 1 --json   # All P0 and P1 issues

Or check GitHub Issues for feature requests and planned improvements.

​General

​What is beads?

​Why beads instead of GitHub Issues or Jira?

​How is beads different from Taskwarrior?

​Can I use beads without AI agents?

​What does “beads” stand for?

​Is beads production-ready?

​Architecture

​Why Dolt instead of plain SQLite or flat files?

​Why hash-based IDs instead of sequential?

​What are hierarchical child IDs?

​Embedded mode or server mode — which am I running?

​Usage

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

​How do I sync issues across machines?

​Do I need to run export/import manually?

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

​How do I handle merge conflicts?

​Can I track issues for multiple projects?

​Can multiple agents work on the same repo?

​Does beads work offline?

​How do I use beads in CI/CD?

​Workflows

​What are formulas?

​What are gates?

​What’s the difference between molecules and wisps?

​Integrations

​Should I use the CLI or MCP?

​How do I integrate with my editor?

​Can beads import from GitHub Issues?

​Migration

​How do I migrate from GitHub Issues, Jira, or Linear?

​Can I export back out of beads?

​Performance

​How does beads handle scale?

​What if my database gets too large?

​Use Cases

​Can I use beads for non-code projects?

​Technical

​What dependencies does beads have?

​Can I query or extend the database directly?

​Does beads support Windows?

​Can I use beads with git worktrees?

​Troubleshooting

​Why is the Dolt server not starting?

​Why aren’t my changes syncing?

​What’s the difference between database corruption and ID collisions?

​How do I report a bug?

​Getting Help

​Where can I get more help?

​How can I contribute?

​Where’s the roadmap?