584608a14e
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
3.3 KiB
id, title, sidebar_position
| 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.
Why a daemon?
The daemon provides:
- Auto-sync with 5-second debounce
- Batched operations for performance
- Background monitoring
Use --no-daemon when not needed (CI, worktrees).
Usage
How do I sync issues to git?
# Auto-sync via daemon (default)
# Or 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?
# Disable daemon in CI
export BEADS_NO_DAEMON=true
# Or per-command
bd --no-daemon 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 daemon not starting?
# Remove stale socket
rm -f .beads/bd.sock
# Restart
bd daemons killall
bd info
Why aren't my changes syncing?
# Check daemon status
bd info
# 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