beads/docs/reference/faq.md
Chris Sells a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00

3.6 KiB

title
FAQ

General

Why beads instead of GitHub Issues or Jira?

Beads was designed specifically for AI-supervised coding workflows:

  • Hash-based IDs prevent collisions with concurrent agents
  • Dolt-backed storage enables branch-based workflows
  • Dependency-aware ready queue for automated work selection
  • Formula system for declarative workflow templates

What does "beads" stand for?

Nothing specific - it's a metaphor for linked work items (like beads on a string).

Is beads production-ready?

Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning.

Architecture

Why Dolt instead of plain SQLite?

  • Dolt provides a version-controlled SQL database with built-in replication
  • Git-like branching, diffing, and merging at the database level
  • No need for a separate sync format -- Dolt handles it natively

Why hash-based IDs instead of sequential?

Sequential IDs (#1, #2) break when:

  • Multiple agents create issues simultaneously
  • Different branches have independent numbering
  • Forks diverge and merge

Hash-based IDs are globally unique without coordination.

How does the Dolt server work?

Beads uses Dolt server mode for concurrent access:

  • Transaction isolation for multiple agents
  • SQL-based queries for performance
  • Automatic retry on conflicts

In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required).

Usage

How do I sync issues?

# Push changes to Dolt remote:
bd dolt push

# Pull changes from Dolt remote:
bd dolt pull

How do I handle merge conflicts?

Dolt handles merge conflicts at the database level. If conflicts arise during pull:

bd doctor --fix
bd dolt push

Can multiple agents work on the same repo?

Yes! That's what beads was designed for:

  • Hash IDs prevent collisions
  • Pin work to specific agents
  • Track who's working on what

How do I use beads in CI/CD?

# Just run commands directly — beads uses embedded mode in CI
bd list

Workflows

What are formulas?

Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).

What are gates?

Async coordination primitives:

  • Human gates wait for approval
  • Timer gates wait for duration
  • GitHub gates wait for CI/PR events

What's the difference between molecules and wisps?

  • Molecules persist in .beads/ and sync with git
  • Wisps are ephemeral in .beads-wisp/ and don't sync

Integration

Should I use CLI or MCP?

Use CLI + hooks when shell is available (Claude Code, Cursor, etc.):

  • Lower context overhead (~1-2k vs 10-50k tokens)
  • Faster execution
  • Universal across editors

Use MCP when CLI unavailable (Claude Desktop).

How do I integrate with my editor?

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

Can beads import from GitHub Issues?

Yes — see the GitHub integration documentation for details.

Troubleshooting

Why is the Dolt server not starting?

# Check server status
bd doctor

# Check server logs
cat .beads/dolt/sql-server.log

# Restart the server
bd dolt stop
bd dolt start

Why aren't my changes syncing?

# Force push to Dolt remote
bd dolt push

# Check hooks
bd hooks status

How do I report a bug?

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