Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/, integrations/, and root to replace removed `bd daemon` references with current Dolt server mode equivalents. CHANGELOG.md preserved per policy. Key replacements: - `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor` - `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor` - `--no-daemon` flag → removed (embedded mode is default) - `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed - `.beads/bd.sock` → removed - "daemon mode" / "direct mode" → "server mode" / "embedded mode" - daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Executed-By: beads/polecats/topaz Rig: beads Role: polecats
3.4 KiB
| id | title | sidebar_position |
|---|---|---|
| faq | FAQ | 5 |
Frequently Asked Questions
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
- Git-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 SQLite + JSONL instead of just one?
- SQLite for fast local queries and complex filtering
- JSONL for git-friendly versioning and sync
- Auto-sync keeps them aligned
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 to git?
# Manual sync:
bd sync
How do I handle merge conflicts?
Install the beads merge driver:
bd init # Prompts for merge driver
Or manually resolve and reimport.
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:
bd import --from github --repo owner/repo
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 sync
bd sync
# Check hooks
bd hooks status
How do I report a bug?
- Check existing issues: https://github.com/steveyegge/beads/issues
- Include:
bd version,bd info --json, reproduction steps - File at: https://github.com/steveyegge/beads/issues/new