Beads Workflow

Overview

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

MCP Tools

GitHub (remote collaboration):

• Link Beads issues to GitHub PRs
• Create GitHub issues for team visibility
• Track PR status for blocked work
• Auto-close Beads issues when PRs merge

Core Commands

Issue Management

# Create a new issue
bd create "Title" -t feature -p 2

# List open issues
bd list --status open

# View issue details
bd show <issue-id>

# Update issue
bd update <id> --status in_progress
bd update <id> --assignee claude

# Close issue
bd close <id> --reason "Completed: description"

Finding Work

# Get unblocked issues (no dependencies blocking)
bd ready --sort hybrid

# Filter by priority
bd list --priority 1 --status open

# Filter by labels
bd list --label backend

Dependencies

# Add dependency (X blocks Y)
bd dep add <blocking-id> <blocked-id> --type blocks

# View dependency tree
bd dep tree <id>

# Remove dependency
bd dep rm <blocking-id> <blocked-id>

Syncing

# Sync with git remote
bd sync

# Force flush to JSONL
bd flush

GitHub Integration Patterns

Linking Issues to PRs

1. Create Beads issue:

   bd create "Feature X"

2. Implement and create PR via GitHub MCP
3. Reference Beads ID in PR description
4. When PR merges, close Beads issue:

   bd close <id>

Syncing Status

# Check if related PR is merged (use GitHub MCP)
# Then update Beads status accordingly
bd update <id> --status done

Team Visibility

For issues that need team visibility:

1. Create in Beads for local tracking
2. Use GitHub MCP to create corresponding GitHub issue
3. Link both in descriptions
4. Keep Beads as source of truth for agents

Workflow Patterns

Starting a Session

1. Check ready work:

   bd ready --sort hybrid

2. Check GitHub: Use GitHub MCP to verify no blocking PRs
3. Claim an issue:

   bd update <id> --status in_progress

4. Review dependencies:

   bd dep tree <id>

5. 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"

4. Create PR: Use GitHub MCP when ready

Completing Work

1. Verify completion: All acceptance criteria met
2. PR status: Use GitHub MCP to check CI/review status
3. Close issue:

   bd close <id> --reason "Implemented X, PR #123"

4. Sync:

   bd sync

5. Check next:

   bd ready

Multi-Agent Coordination

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

# Avoid conflicts - check before claiming
bd show <id>  # Check assignee field

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

Issue Types

feature

bug

task

spike

chore

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
6. Link to GitHub: Create GitHub issues for team-visible work

Integration with Swarm

When working in a swarm:

1. Check active work:

   bd list --status in_progress

2. Claim before editing: Update status before touching code
3. Document blockers: Create issues for discovered blockers
4. Handoff cleanly: Update assignee and add context
5. Sync before ending:

   bd sync

   to share state
6. Create PRs: Use GitHub MCP for review visibility

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