beads/examples
Chris Sells 54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
2026-07-12 10:37:07 -07:00
..
bash-agent Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
bd-example-extension-go docs: canonical concept page, section overviews, and concept diagrams 2026-07-12 10:37:07 -07:00
claude-desktop-mcp bd sync: 2025-11-26 18:07:01 2025-11-26 18:07:01 -08:00
compaction fix(compact): stop advertising the unimplemented Tier 2 compaction (#4465) 2026-06-20 15:29:28 -07:00
contributor-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
formulas feat(formula): make primitives discoverable to coding agents (GH#3621) (#3781) 2026-07-06 22:26:41 -07:00
library-usage docs: resolve legacy extension guide reference (#3810) 2026-05-08 08:24:31 -07:00
linear-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
multi-phase-development docs(claim): standardize start-work semantics to --claim (#2070) 2026-02-24 22:11:39 -08:00
multiple-personas docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
protected-branch docs: canonical concept page, section overviews, and concept diagrams 2026-07-12 10:37:07 -07:00
python-agent Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
startup-hooks feat: Add agent upgrade awareness documentation and tooling 2025-11-23 16:29:56 -08:00
team-workflow docs(ci): add Mintlify preview, docsync guard, and broken-links workflow 2026-07-12 10:37:07 -07:00
README.md docs(claim): standardize start-work semantics to --claim (#2070) 2026-02-24 22:11:39 -08:00

Beads Examples

This directory contains examples of how to integrate bd with AI agents and workflows.

Examples

Agent Integration

Tools & Utilities

  • monitor-webui/ - Standalone web interface for real-time issue monitoring and visualization
  • git-hooks/ - Pre-configured git hooks for automatic Dolt sync

Workflow Patterns

Quick Start

# Try the Python agent example
cd python-agent
python agent.py

# Try the bash agent example
cd bash-agent
./agent.sh

# Install git hooks
cd git-hooks
./install.sh

# REMOVED (bd-4c74): branch-merge demo - hash IDs eliminate collision resolution

Creating Your Own Agent

The basic agent workflow:

  1. Find ready work: bd ready --json --limit 1
  2. Claim the task: bd update <id> --claim --json
  3. Do the work: Execute the task
  4. Discover new issues: bd create "Found bug" --json
  5. Link discoveries: bd dep add <new-id> <parent-id> --type discovered-from
  6. Complete the task: bd close <id> --reason "Done" --json

All commands support --json for easy parsing.