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
