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

Command	Description
bd create "Title" -t feature -p 2	Create issue (type, priority)
bd list --status open	List open issues
bd show <id>	View issue details
bd update <id> --status in_progress	Update status or assignee
bd close <id> --reason "..."	Close with reason
bd ready --sort hybrid	Find unblocked issues
bd dep add <blocking> <blocked> --type blocks	Add dependency
bd dep tree <id>	View dependency tree
bd dep rm <blocking> <blocked>	Remove dependency
bd sync	Sync with git remote
bd flush	Force flush to JSONL

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

Type	When to Use
feature	New functionality
bug	Defect fixes
task	General work items
spike	Research/investigation
chore	Maintenance, cleanup

Priority Levels

Priority	Meaning
0	Critical - Drop everything
1	High - Next up
2	Medium - Normal flow
3	Low - When time permits
4	Backlog - Future consideration

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