Beads Workflow

Beads is an AI-native issue tracker designed for agent workflows. Issues live in your repo, sync via git, and require no web UI.

Core Commands

Workflow Patterns

Starting a Session

1. Check ready work: bd ready --sort hybrid
2. Claim an issue: bd update <id> --status in_progress
3. Review dependencies: bd dep tree <id>
4. Begin implementation

During Implementation

1. Track sub-tasks: bd create "Sub-task" --parent <id>
2. Add blockers: bd dep add <new-blocker> <id> --type blocks
3. Update progress: bd comment <id> "Progress update"

Completing Work

1. Verify completion: All acceptance criteria met
2. Close issue: bd close <id> --reason "Implemented X, PR #123"
3. Sync: bd sync
4. Check next: bd ready

Multi-Agent Coordination

# See who's working on what
bd list --status in_progress --json | jq '.[] | {id, title, assignee}'

# Hand off work
bd update <id> --assignee other-agent
bd comment <id> "Handoff: context and next steps"

Issue Types

Priority Levels

Status Flow

open -> in_progress -> done
         |-> blocked -> in_progress

Best Practices

1. One issue per logical unit: Don't combine unrelated work
2. Clear titles: Should explain what, not how
3. Use dependencies: Makes ready work visible
4. Sync frequently: Keep other agents informed
5. Close promptly: Don't leave stale in_progress issues

Integration with Swarm

1. Claim before editing: Update status before touching code
2. Document blockers: Create issues for discovered blockers
3. Handoff cleanly: Update assignee and add context
4. Sync before ending: bd sync to share state

Troubleshooting

# Check daemon health
bd daemons health

# View daemon logs
bd daemons logs

# Force reimport from JSONL
bd import --force

# Check for conflicts
bd sync --dry-run