Beads Examples

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

Examples

Agent Integration

• python-agent/ - Simple Python agent that discovers ready work and completes tasks
• bash-agent/ - Bash script showing the full agent workflow
• startup-hooks/ - Session startup scripts for automatic bd upgrade detection
• claude-desktop-mcp/ - MCP server for Claude Desktop 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

• contributor-workflow/ - OSS contributor setup with separate planning repo
• team-workflow/ - Team collaboration with shared repositories
• multi-phase-development/ - Organize large projects by phases (planning, MVP, iteration, polish)
• multiple-personas/ - Architect/implementer/reviewer role separation
• protected-branch/ - Protected branch workflow for team collaboration

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.