Beads Session Workflow

Daily workflow protocols for managing work sessions with Beads issue tracking and git integration.

Overview

Beads integrates seamlessly with git-based workflows, enabling:

Automatic sync: Commit, pull, push issue changes
Session context: Prime AI agents with current work state
Work discovery: Find ready tasks at session start
Progress tracking: Review stats at session end
Multi-device support: Sync issues across clones via git branches

The session workflow ensures issues stay synchronized, agents stay informed, and work stays focused.

Canonical Sources

Command Reference:

bd sync --help      # Git synchronization
bd ready --help     # Finding unblocked work
bd stats --help     # Database statistics
bd status --help    # Overview of issue database
bd prime --help     # AI workflow context
bd daemon --help    # Background sync daemon

Session Commands (if available in .claude/commands/):

bd prime for AI session context
Git hooks for automatic sync on commit

Patterns

Session Start Protocol

# 1. Sync issues from remote
cd /path/to/project
bd sync

# 2. Review database status
bd status

# Output:
# Total Issues:      622
# Open:              245
# In Progress:       3
# Blocked:           53
# Ready to Work:     192

# 3. Find unblocked work
bd ready --limit 10 --sort hybrid

# 4. (Optional) Prime AI agent with workflow context
bd prime

# 5. Start work on selected issue
bd update tmnl-abc --status in_progress

During Session: Incremental Sync

# Create issues as work progresses
bd create "Implement feature X" --type task --priority P1

# Update status as you work
bd update tmnl-abc --status in_progress

# Sync changes to remote (squash mode for fewer commits)
bd sync --squash

# Continue working...

# When ready to commit all accumulated changes
bd sync --message "Session progress: completed 3 tasks"

Session End Protocol

# 1. Update issue status
bd update tmnl-abc --status closed --notes "Completed and tested"
bd update tmnl-xyz --status in_progress --notes "WIP: need to finish tests"

# 2. Review session statistics
bd stats

# Output shows counts by type, status, priority

# 3. Final sync to remote
bd sync --message "End of session: closed tmnl-abc, WIP tmnl-xyz"

# 4. (Optional) Review what's ready for next session
bd ready --limit 5

Git Integration Workflow

# Standard git workflow with beads sync
git checkout -b feat/new-feature

# Work on code
bd update tmnl-abc --status in_progress

# Sync issues alongside code changes
git add .
git commit -m "Implement feature X"
bd sync  # Auto-commit issues, pull, push

# Continue iterating
# ...

# When feature complete
bd close tmnl-abc --reason "Feature implemented"
git push origin feat/new-feature
bd sync  # Push issue updates

Sync Modes

# Full sync: export, commit, pull, push
bd sync

# Custom commit message
bd sync --message "Daily standup: closed 2 bugs, created 1 epic"

# Dry run (preview without changes)
bd sync --dry-run

# Squash mode: accumulate changes without committing
bd sync --squash  # Run multiple times during session
bd sync           # Final commit when ready

# Flush only: export to JSONL without git ops
bd sync --flush-only

# Import only: load from JSONL after manual git pull
git pull origin master
bd sync --import-only

# No push: sync locally without pushing to remote
bd sync --no-push

# No pull: skip pulling from remote
bd sync --no-pull

# One-way sync from main (for ephemeral branches)
bd sync --from-main

Daemon Mode (Background Sync)

# Start background sync daemon
bd daemon start

# Daemon auto-syncs on CRUD operations
bd create "Task"  # Auto-synced in background

# Check daemon status
bd daemon status

# Stop daemon
bd daemon stop

# View daemon logs
tail -f .beads/daemon.log

Work Discovery Patterns

# Find high-priority unblocked work
bd ready --priority 0 --limit 5

# Find unassigned work
bd ready --unassigned --limit 10

# Find work by label
bd ready --label frontend --limit 10

# Sort by oldest first (tackle stale issues)
bd ready --sort oldest --limit 5

# Sort by priority
bd ready --sort priority --limit 10

# Hybrid sort (balances priority + age)
bd ready --sort hybrid --limit 10

Issue Status Tracking

# Show current work in progress
bd list --status in_progress

# Show blocked work (needs unblocking)
bd blocked

# Show recently closed issues
bd list --status closed --closed-after 2025-12-19

# Show stale issues (not updated recently)
bd stale --days 30

Examples

Example 1: Morning Session Start

# 1. Pull latest changes from remote
cd ~/projects/tmnl
git pull origin master

# 2. Sync issues
bd sync

# 3. Check overall status
bd status

# 4. Find ready work
bd ready --limit 10

# Output:
# 📋 Ready work (10 issues):
# 1. [P0] tmnl-abc: Fix authentication bug
# 2. [P0] tmnl-xyz: Implement search indexing
# 3. [P1] tmnl-def: Add profile UI component
# ...

# 5. Select and start task
bd update tmnl-abc --status in_progress --assignee val

# 6. Prime AI agent (if using Claude Code)
bd prime

# Output:
# Beads Workflow Context for AI:
# - Use `bd create` to track new issues
# - Use `bd ready` to find unblocked work
# - Use `bd sync` to synchronize with git
# ...

Example 2: Mid-Session Progress Sync

# Working on feature, discover subtasks
bd create "Add validation logic" --type task --priority P1
bd create "Write unit tests" --type task --priority P1

# Squash sync (accumulate changes)
bd sync --squash

# Continue working...

# Discover a bug
bd create "Fix null pointer in validator" \
  --type bug \
  --priority P0 \
  --deps "discovered-from:tmnl-validation"

# Squash sync again
bd sync --squash

# Eventually, commit all accumulated changes
bd sync --message "Feature development: validation + tests + bugfix"

Example 3: Evening Session Close

# 1. Update status of in-progress work
bd update tmnl-abc --notes "Completed core logic, tests pending"

# 2. Close completed issues
bd close tmnl-xyz --reason "Implemented and tested"

# 3. Review session stats
bd stats

# Output:
# Issue Statistics:
# By Status:
#   Open:           240 (38.6%)
#   In Progress:    4 (0.6%)
#   Blocked:        53 (8.5%)
#   Closed:         375 (60.3%)
#
# By Type:
#   Task:           450 (72.3%)
#   Bug:            80 (12.9%)
#   Feature:        60 (9.6%)
#   Epic:           20 (3.2%)
#   Chore:          12 (1.9%)
#
# By Priority:
#   P0:             25 (4.0%)
#   P1:             80 (12.9%)
#   P2:             400 (64.3%)
#   P3:             100 (16.1%)
#   P4:             17 (2.7%)

# 4. Final sync
bd sync --message "Session close: completed tmnl-xyz, WIP tmnl-abc"

# 5. Preview next session's work
bd ready --limit 5 --sort priority

Example 4: Multi-Device Sync

# Device 1 (laptop)
bd create "Add feature X" --type task --priority P1
bd sync  # Push to remote

# Device 2 (desktop)
git pull origin master
bd sync  # Import new issue
bd update tmnl-feature-x --status in_progress
bd sync  # Push status update

# Device 1 (laptop)
bd sync  # Pull status update
bd show tmnl-feature-x
# Output: Status: in_progress (updated from Device 2)

Example 5: Git Hook Integration

# Install git hooks for auto-sync (if supported)
bd hooks install

# Now git commit auto-triggers bd sync --flush-only
git add .
git commit -m "Implement feature"
# (Beads issues auto-exported to .beads/issues.jsonl)

# Manual sync for pull/push
bd sync

# Uninstall hooks if needed
bd hooks uninstall

Example 6: Session Recovery After Conflict

# Sync fails due to merge conflict
bd sync

# Output:
# Error: Merge conflict in .beads/issues.jsonl

# Resolve manually or use bd merge driver
git status
git mergetool  # Uses bd merge driver if configured

# After resolving conflict
git add .beads/issues.jsonl
git commit -m "Merge beads issues"
bd sync --import-only  # Reload from JSONL

# Verify database consistency
bd validate

Anti-Patterns

DON'T: Skip syncing before session start

# WRONG - start work without syncing
bd ready  # Shows stale data
bd update tmnl-abc --status in_progress  # May conflict with remote

# CORRECT - always sync first
bd sync
bd ready
bd update tmnl-abc --status in_progress

DON'T: Forget to sync at session end

# WRONG - leave changes unsynced
bd create "Task"
bd update tmnl-abc --status closed
# (Exit session without syncing)

# CORRECT - always sync before ending
bd create "Task"
bd update tmnl-abc --status closed
bd sync --message "Session close"

DON'T: Work on stale issue data

# WRONG - skip checking if data is stale
bd list --status open  # Shows stale data from days ago

# CORRECT - sync first
bd sync  # Pull latest
bd list --status open  # Fresh data

DON'T: Use conflicting sync flags

# WRONG - contradictory flags
bd sync --flush-only --import-only  # Can't do both!

# CORRECT - use one mode at a time
bd sync --flush-only  # Export only
# OR
bd sync --import-only  # Import only

DON'T: Ignore daemon errors

# WRONG - daemon fails silently, manual sync needed
bd daemon status
# Output: Daemon not running (crashed)

# (Continue working without syncing)

# CORRECT - restart daemon or use manual sync
bd daemon start
# OR
bd sync  # Manual sync as fallback

DON'T: Create excessive commit noise

# WRONG - sync after every tiny change
bd create "Task 1"
bd sync  # Commit 1
bd create "Task 2"
bd sync  # Commit 2
bd update tmnl-abc --status in_progress
bd sync  # Commit 3

# CORRECT - use squash mode
bd create "Task 1"
bd sync --squash
bd create "Task 2"
bd sync --squash
bd update tmnl-abc --status in_progress
bd sync --message "Batch: created 2 tasks, started work on tmnl-abc"

Quick Reference Card

Task	Command
Start session	`bd sync && bd ready --limit 10`
End session	`bd stats && bd sync`
Full sync	`bd sync`
Squash mode	`bd sync --squash`
Dry run	`bd sync --dry-run`
Custom commit	`bd sync --message "Session work"`
Find ready work	`bd ready --limit 10`
Review stats	`bd stats`
Database status	`bd status`
Prime AI	`bd prime`
Start daemon	`bd daemon start`
Check daemon	`bd daemon status`

Session Checklist

Morning Start

cd to project directory
git pull origin master
bd sync to import latest issues
bd status to review database
bd ready --limit 10 to find unblocked work
bd update [id] --status in_progress to start work
bd prime to brief AI agent (if applicable)

During Session

bd create to track new issues as discovered
bd update to track progress on active issues
bd sync --squash for incremental sync (optional)
bd ready to check for new unblocked work

Evening Close

bd update to finalize status of in-progress work
bd close for completed issues with --reason
bd stats to review session productivity
bd sync --message "Session summary" to push changes
bd ready --limit 5 to preview next session's work

Integration Points

Git workflow: Issues committed alongside code changes
AI agents: Use bd prime to provide workflow context
Issue management: Use bd ready and bd blocked (see beads-issue-management skill)
Dependencies: Sync preserves dependency relationships (see beads-dependency-tracking skill)
Templates: Session-specific templates via bd template
Daemon: Background auto-sync for seamless workflow

Sync Branch Workflow

Beads supports multi-clone setups via dedicated sync branches:

# Initialize sync branch workflow
bd migrate-sync

# Sync uses dedicated branch (e.g., beads-sync)
bd sync  # Auto-commits to sync branch, not main

# View sync branch status
bd sync --status

# Merge sync branch to main when ready
bd sync --merge

# One-way sync from main (for ephemeral feature branches)
bd sync --from-main

Troubleshooting

Sync conflicts

# If merge conflict occurs
bd sync  # Reports conflict
git status  # Check conflicted files
git mergetool  # Resolve with bd merge driver
git commit -m "Merge beads issues"
bd sync --import-only  # Reload

Stale data warnings

# If bd warns about stale data
bd sync --allow-stale  # Override check (use cautiously)
# Better: sync first
bd sync  # Update to latest

Daemon issues

# Daemon not responding
bd daemon status  # Check status
bd daemon stop && bd daemon start  # Restart
tail -f .beads/daemon.log  # Check logs

Database corruption

# Run health check
bd validate

# Repair orphaned dependencies
bd repair-deps

# If severe, re-import from JSONL
mv .beads/beads.db .beads/beads.db.backup
bd sync --import-only  # Rebuild from JSONL