Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides persistent memory that survives conversation compaction. Use when work spans multiple sessions, has complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or "update status".
Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides persistent memory that survives conversation compaction. Use when work spans multiple sessions, has complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or "update status".
allowed-tools
Read,Bash(bd:*)
version
0.34.0
author
Steve Yegge <https://github.com/steveyegge>
license
MIT
Beads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
Overview
bd (beads) replaces markdown task lists with a dependency-aware graph stored in git. Unlike TodoWrite (session-scoped), bd persists across compactions and tracks complex dependencies.
Dependency graph (what blocks this, what this blocks)
Audit trail (all status changes, notes)
Metadata (created, updated, assignee, labels)
Step 4: Start Working
bd update <task-id> --status in_progress
Marks task as actively being worked on.
Step 5: Add Notes as You Work
bd update <task-id> --notes "Completed: X. In progress: Y. Blocked by: Z"
Critical for compaction survival: Write notes as if explaining to a future agent with zero conversation context.
Note Format (best practice):
COMPLETED: Specific deliverables (e.g., "implemented JWT refresh endpoint + rate limiting")
IN PROGRESS: Current state + next immediate step
BLOCKERS: What's preventing progress
KEY DECISIONS: Important context or user guidance
Task Creation Workflow
When to Create Tasks
Create bd tasks when:
User mentions tracking work across sessions
User says "we should fix/build/add X"
Work has dependencies or blockers
Exploratory/research work with fuzzy boundaries
Basic Task Creation
bd create "Task title" -p 1 --type task
Arguments:
Title: Brief description (required)
Priority: 0-4 where 0=critical, 1=high, 2=medium, 3=low, 4=backlog (default: 2)
Labels provide cross-cutting categorization beyond status/type.
Dependency Management
Add Dependencies
bd dep add <child-id> <parent-id>
Meaning: <parent-id> blocks <child-id> (parent must be completed first).
Dependency Types:
blocks: Parent must close before child becomes ready
parent-child: Hierarchical relationship (epics and subtasks)
discovered-from: Task A led to discovering task B
related: Tasks are related but not blocking
Example:
# Deployment blocked by tests passing
bd dep add deploy-task test-task # test-task blocks deploy-task
View Dependencies
bd dep list <task-id>
Shows:
What this task blocks (dependents)
What blocks this task (blockers)
Circular Dependency Prevention
bd automatically prevents circular dependencies. If you try to create a cycle, the command fails.
Completion Workflow
Close a Task
bd close <task-id> --reason "Completion summary"
Best Practice: Always include a reason describing what was accomplished.
Example:
bd close myproject-abc --reason "Completed: OAuth endpoints implemented with Google, GitHub providers. Tests passing."
Check Newly Unblocked Work
After closing a task, run:
bd ready
Closing a task may unblock dependent tasks, making them newly ready.
Close Epics When Children Complete
bd epic close-eligible
Automatically closes epics where all child tasks are closed.
Git Sync Workflow
All-in-One Sync
bd sync
Performs:
Export database to .beads/issues.jsonl
Commit changes to git
Pull from remote (merge if needed)
Import updated JSONL back to database
Push local commits to remote
Use when: End of session, before handing off to teammate, after major progress.
Export Only
bd export -o backup.jsonl
Creates JSONL backup without git operations.
Import Only
bd import -i backup.jsonl
Imports JSONL file into database.
Background Daemon
bd daemon --start # Auto-sync in background
bd daemon --status # Check daemon health
bd daemon --stop # Stop auto-sync
Daemon watches for database changes and auto-exports to JSONL.
Find & Search Commands
Find Ready Work
bd ready
Shows tasks with no open blockers.
List All Tasks
bd list --status open # Only open tasks
bd list --priority 0 # Only P0 (critical)
bd list --type bug # Only bugs
bd list --label backend # Only labeled "backend"
bd list --assignee alice # Only assigned to alice
Show Task Details
bd show <task-id>
Full details: description, dependencies, audit trail, metadata.
Search by Text
bd search "authentication"# Search titles and descriptions
bd search login --status open # Combine with filters
Find Blocked Work
bd blocked
Shows all tasks that have open blockers preventing them from being worked on.
Project Statistics
bd stats
Shows:
Total issues by status (open, in_progress, blocked, closed)
Issues by priority (P0-P4)
Issues by type (bug, feature, task, epic, chore)
Completion rate
Complete Command Reference
Command
When to Use
Example
FIND COMMANDS
bd ready
Find unblocked tasks
User asks "what should I work on?"
bd list
View all tasks (with filters)
"Show me all open bugs"
bd show <id>
Get task details
"Show me task bd-42"
bd search <query>
Text search across tasks
"Find tasks about auth"
bd blocked
Find stuck work
"What's blocking us?"
bd stats
Project metrics
"How many tasks are open?"
CREATE COMMANDS
bd create
Track new work
"Create a task for this bug"
bd template create
Use issue template
"Create task from bug template"
bd init
Initialize beads
"Set up beads in this repo" (humans only)
UPDATE COMMANDS
bd update <id>
Change status/priority/notes
"Mark as in progress"
bd dep add
Link dependencies
"This blocks that"
bd label add
Tag with labels
"Label this as backend"
bd comments add
Add comment
"Add comment to task"
bd reopen <id>
Reopen closed task
"Reopen bd-42, found regression"
bd rename-prefix
Rename issue prefix
"Change prefix from bd- to proj-"
bd epic status
Check epic progress
"Show epic completion %"
COMPLETE COMMANDS
bd close <id>
Mark task done
"Close this task, it's done"
bd epic close-eligible
Auto-close complete epics
"Close epics where all children done"
SYNC COMMANDS
bd sync
Git sync (all-in-one)
"Sync tasks to git"
bd export
Export to JSONL
"Backup all tasks"
bd import
Import from JSONL
"Restore from backup"
bd daemon
Background sync manager
"Start auto-sync daemon"
CLEANUP COMMANDS
bd delete <id>
Delete issues
"Delete test task" (requires --force)
bd compact
Archive old closed tasks
"Compress database"
REPORTING COMMANDS
bd stats
Project metrics
"Show project health"
bd audit record
Log interactions
"Record this LLM call"
bd workflow
Show workflow guide
"How do I use beads?"
ADVANCED COMMANDS
bd prime
Refresh AI context
"Load bd workflow rules"
bd quickstart
Interactive tutorial
"Teach me beads basics"
bd daemons
Multi-repo daemon mgmt
"Manage all beads daemons"
bd version
Version check
"Check bd version"
bd restore <id>
Restore compacted issue
"Get full history from git"
Output
This skill produces:
Task IDs: Format <prefix>-<hash> (e.g., claude-code-plugins-abc, myproject-xyz)
Status Summaries:
5 open, 2 in_progress, 1 blocked, 47 closed
Dependency Graphs (visual tree):
myproject-abc: Deploy to production [P0] [blocked]
Blocked by:
↳ myproject-def: Run integration tests [P1] [in_progress]
↳ myproject-ghi: Fix failing tests [P1] [open]
Audit Trails (complete history):
2025-12-22 10:00 - Created by alice (P2, task)
2025-12-22 10:15 - Priority changed: P2 → P0
2025-12-22 10:30 - Status changed: open → in_progress
2025-12-22 11:00 - Notes added: "Implemented JWT auth..."
2025-12-22 14:00 - Status changed: in_progress → blocked
2025-12-22 14:01 - Notes added: "Blocked: API endpoint returns 503"
# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Or via npm
npm install -g @beads/bd
# Or via Homebrew
brew install steveyegge/beads/bd
2. No .beads database found
Cause: beads not initialized in this repository
Solution: Run bd init (humans do this once, not agents)
bd init # Creates .beads/ directory
3. Task not found: <id>
Cause: Invalid task ID or task doesn't exist
Solution: Use bd list to see all tasks and verify ID format
bd list # See all tasks
bd search <partial-title> # Find task by title
4. Circular dependency detected
Cause: Attempting to create a dependency cycle (A blocks B, B blocks A)
Solution: bd prevents circular dependencies automatically. Restructure dependency graph.
bd dep list <id> # View current dependencies
5. Git merge conflicts in .beads/issues.jsonl
Cause: Multiple users modified same issue
Solution: bd sync handles JSONL conflicts automatically. If manual intervention needed:
bd ready
# Shows: myproject-auth [P1] [task] in_progress
bd show myproject-auth
# Full context preserved:# - Title: Implement user authentication# - Status: in_progress# - Notes: "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting"# - No conversation history needed!# Agent continues exactly where it left off
bd update myproject-auth --notes "COMPLETED: Token refresh working. IN PROGRESS: Rate limiting implementation"
Result: Zero context loss despite compaction.
Example 4: Complex Dependencies (3-Level Graph)
Scenario: Build feature with prerequisites
# Create tasks
bd create "Deploy to production" -p 0
# Returns: deploy-prod
bd create "Run integration tests" -p 1
# Returns: integration-tests
bd create "Fix failing unit tests" -p 1
# Returns: fix-tests# Create dependency chain
bd dep add deploy-prod integration-tests # Integration blocks deploy
bd dep add integration-tests fix-tests # Fixes block integration# Check what's ready
bd ready
# Shows: fix-tests (no blockers)# Hides: integration-tests (blocked by fix-tests)# Hides: deploy-prod (blocked by integration-tests)# Work on ready task
bd update fix-tests --status in_progress
# ... fix tests ...
bd close fix-tests --reason "All unit tests passing"# Check ready again
bd ready
# Shows: integration-tests (now unblocked!)# Still hides: deploy-prod (still blocked)
Result: Dependency chain enforces correct order automatically.
Example 5: Team Collaboration (Git Sync)
Alice's Session:
bd create "Refactor database layer" -p 1
bd update db-refactor --status in_progress
bd update db-refactor --notes "Started: Migrating to Prisma ORM"# End of day - sync to git
bd sync# Commits tasks to git, pushes to remote
Bob's Session (next day):
# Start of day - sync from git
bd sync# Pulls latest tasks from remote
bd ready
# Shows: db-refactor [P1] [in_progress] (assigned to alice)# Bob checks status
bd show db-refactor
# Sees Alice's notes: "Started: Migrating to Prisma ORM"# Bob works on different task (no conflicts)
bd create "Add API rate limiting" -p 2
bd update rate-limit --status in_progress
# End of day
bd sync# Both Alice's and Bob's tasks synchronized
Result: Distributed team coordination through git.
Resources
When to Use bd vs TodoWrite (Decision Tree)
Use bd when:
✅ Work spans multiple sessions or days
✅ Tasks have dependencies or blockers
✅ Need to survive conversation compaction
✅ Exploratory/research work with fuzzy boundaries
✅ Collaboration with team (git sync)
Use TodoWrite when:
✅ Single-session linear tasks
✅ Simple checklist for immediate work
✅ All context is in current conversation
✅ Will complete within current session
Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.
Essential Commands Quick Reference
Top 10 most-used commands:
Command
Purpose
bd ready
Show tasks ready to work on
bd create "Title" -p 1
Create new task
bd show <id>
View task details
bd update <id> --status in_progress
Start working
bd update <id> --notes "Progress"
Add progress notes
bd close <id> --reason "Done"
Complete task
bd dep add <child> <parent>
Add dependency
bd list
See all tasks
bd search <query>
Find tasks by keyword
bd sync
Sync with git remote
Session Start Protocol (Every Session)
Runbd ready first
Pick highest priority ready task
Runbd show <id> to get full context
Update status to in_progress
Add notes as you work (critical for compaction survival)
Progressive Disclosure: This skill provides essential instructions for all 30 beads commands. For advanced topics (compaction, templates, team workflows), see the references directory. Slash commands (/bd-create, /bd-ready, etc.) remain available as explicit fallback for power users.
