beads/website/static/llms.txt
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

79 lines
2.5 KiB
Text

# Beads (bd)
> Dolt-powered issue tracker for AI-supervised coding workflows.
> CLI with formulas, molecules, and multi-agent coordination.
## Quick Start
Install:
```bash
brew install beads
```
Initialize:
```bash
cd your-project && bd init --quiet
```
## Essential Commands
```bash
bd create "Title" -t bug -p 1 --json # Create issue
bd list --status open --json # List issues
bd show bd-42 --json # Show details
bd update bd-42 --claim # Start work
bd close bd-42 --reason "Done" # Close issue
bd ready --json # Show unblocked work
bd dolt push # Push to Dolt remote
bd backup export-git # Publish backup snapshot to a git branch
```
## For AI Agents
- Always use `--json` for programmatic access
- Always include `--description` when creating issues
- Use `--deps discovered-from:<id>` to link found issues
- Use `bd dolt push` / `bd dolt pull` for Dolt remotes
- Use `bd backup` / `bd backup export-git` for portable backups
## Key Concepts
- **Issues**: Work items with priorities (0-4), types (bug/feature/task/epic/chore)
- **Dependencies**: `blocks` (affects ready queue), `parent-child`, `discovered-from`, `related`
- **Formulas**: Declarative workflow templates (TOML/JSON)
- **Molecules**: Work graphs from formulas
- **Gates**: Async coordination (human/timer/github)
- **Wisps**: Ephemeral workflows (excluded from JSONL backups)
## Recovery
Quick fixes for common issues:
- Database Recovery: `bd backup restore` or `bd backup fetch-git`
- Merge Conflicts: Use Dolt merge/recovery tools, then `bd dolt pull`
- Circular Dependencies: `bd doctor` (diagnose only, NEVER --fix)
- Sync Failures: `bd dolt pull`
Full runbooks: https://gastownhall.github.io/beads/recovery/
## Session Close Protocol
Before ending any AI session:
1. `bd dolt push` - if using a Dolt remote
2. `git push` - publish your code changes
3. Resolve conflicts before closing
WARNING: Skipping sync or backup publication causes stale state in multi-agent workflows.
## Documentation
- Full docs: https://gastownhall.github.io/beads/
- CLI reference: https://gastownhall.github.io/beads/cli-reference
- Agent guide: https://gastownhall.github.io/beads/integrations/claude-code
- Complete LLM context: https://gastownhall.github.io/beads/llms-full.txt
## Links
- GitHub: https://github.com/gastownhall/beads
- npm: https://www.npmjs.com/package/@beads/bd
- PyPI (MCP): https://pypi.org/project/beads-mcp/