beads/website/versioned_docs/version-1.0.0/reference/faq.md
Ben Madore 3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00

158 lines
3.6 KiB
Markdown

---
id: faq
title: FAQ
sidebar_position: 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
- **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?
```bash
# 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:
```bash
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?
```bash
# 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?
```bash
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](https://github.com/gastownhall/beads/blob/main/docs/GITHUB_IMPORT.md) for details.
## Troubleshooting
### Why is the Dolt server not starting?
```bash
# 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?
```bash
# 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