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
-
Check ready work: bd ready --sort hybrid
-
Claim an issue: bd update <id> --status in_progress
-
Review dependencies: bd dep tree <id>
-
Begin implementation
During Implementation
-
Track sub-tasks: bd create "Sub-task" --parent <id>
-
Add blockers: bd dep add <new-blocker> <id> --type blocks
-
Update progress: bd comment <id> "Progress update"
Completing Work
-
Verify completion: All acceptance criteria met
-
Close issue: bd close <id> --reason "Implemented X, PR #123"
-
Sync: bd sync
-
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
-
One issue per logical unit: Don't combine unrelated work
-
Clear titles: Should explain what, not how
-
Use dependencies: Makes ready work visible
-
Sync frequently: Keep other agents informed
-
Close promptly: Don't leave stale in_progress issues
Integration with Swarm
-
Claim before editing: Update status before touching code
-
Document blockers: Create issues for discovered blockers
-
Handoff cleanly: Update assignee and add context
-
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