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.

Key Distinction:

• bd: Multi-session work, dependencies, survives compaction, git-backed
• TodoWrite: Single-session tasks, linear execution, conversation-scoped

Core Capabilities:

• 📊 Dependency Graphs: Track what blocks what (blocks, parent-child, discovered-from, related)
• 💾 Compaction Survival: Tasks persist when conversation history is compacted
• 🐙 Git Integration: Issues versioned in .beads/issues.jsonl, sync with bd sync
• 🔍 Smart Discovery: Auto-finds ready work (bd ready), blocked work (bd blocked)
• 📝 Audit Trails: Complete history of status changes, notes, and decisions
• 🏷️ Rich Metadata: Priority (P0-P4), types (bug/feature/task/epic), labels, assignees

When to Use bd vs TodoWrite:

• ❓ "Will I need this context in 2 weeks?" → YES = bd
• ❓ "Could conversation history get compacted?" → YES = bd
• ❓ "Does this have blockers/dependencies?" → YES = bd
• ❓ "Is this fuzzy/exploratory work?" → YES = bd
• ❓ "Will this be done in this session?" → YES = TodoWrite
• ❓ "Is this just a task list for me right now?" → YES = TodoWrite

Decision Rule: If resuming in 2 weeks would be hard without bd, use bd.

Prerequisites

Required:

• bd CLI: Version 0.34.0 or later installed and in PATH
• Git Repository: Current directory must be a git repo
• Initialization: bd init must be run once (humans do this, not agents)

Verify Installation:

bd --version  # Should return 0.34.0 or later

First-Time Setup (humans run once):

cd /path/to/your/repo
bd init  # Creates .beads/ directory with database

Optional:

• BEADS_DIR environment variable for alternate database location
• Daemon for background sync: bd daemon --start

Instructions

Session Start Protocol

Every session, start here:

Step 1: Check for Ready Work

bd ready

Shows tasks with no open blockers, sorted by priority (P0 → P4).

What this shows:

• Task ID (e.g., myproject-abc)
• Title
• Priority level
• Issue type (bug, feature, task, epic)

Example output:

claude-code-plugins-abc [P1] [task] open
  Implement user authentication

claude-code-plugins-xyz [P0] [epic] in_progress
  Refactor database layer

Step 2: Pick Highest Priority Task

Choose the highest priority (P0 > P1 > P2 > P3 > P4) task that's ready.

Step 3: Get Full Context

bd show <task-id>

Displays:

• Full task description
• 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)
• Type: bug, feature, task, epic, chore (default: task)

Example:

bd create "Fix authentication bug" -p 0 --type bug

Create with Description

bd create "Implement OAuth" -p 1 --description "Add OAuth2 support for Google, GitHub, Microsoft. Use passport.js library."

Epic with Children

# Create parent epic
bd create "Epic: OAuth Implementation" -p 0 --type epic
# Returns: myproject-abc

# Create child tasks
bd create "Research OAuth providers" -p 1 --parent myproject-abc
bd create "Implement auth endpoints" -p 1 --parent myproject-abc
bd create "Add frontend login UI" -p 2 --parent myproject-abc

---

Update & Progress Workflow

Change Status

bd update <task-id> --status <new-status>

Status Values:

• open - Not started
• in_progress - Actively working
• blocked - Stuck, waiting on something
• closed - Completed

Example:

bd update myproject-abc --status blocked

Add Progress Notes

bd update <task-id> --notes "Progress update here"

Appends to existing notes field (doesn't replace).

Change Priority

bd update <task-id> -p 0  # Escalate to critical

Add Labels

bd label add <task-id> backend
bd label add <task-id> security

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:

1. Export database to .beads/issues.jsonl
2. Commit changes to git
3. Pull from remote (merge if needed)
4. Import updated JSONL back to database
5. 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"

---

Error Handling

Common Failures

1. bd: command not found

Cause: bd CLI not installed or not in PATH Solution: Install from https://github.com/steveyegge/beads

# 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:

# View conflict
git status

# bd provides conflict resolution tools
bd sync --merge  # Attempt auto-resolution

6. Database is locked

Cause: Daemon or another process has exclusive lock Solution: Restart daemon or wait for lock to release

bd daemon --stop
bd daemon --start

7. Sync failures

Cause: Network issues, authentication failures, or git configuration Solution: Check git remote access and credentials

git fetch  # Test connectivity
git status # Verify repo state

---

Examples

Example 1: Multi-Session Feature (Epic with Children)

User Request: "We need to implement OAuth, this will take multiple sessions"

Agent Response:

# Create epic
bd create "Epic: OAuth Implementation" -p 0 --type epic
# Returns: claude-code-plugins-abc

# Create child tasks
bd create "Research OAuth providers (Google, GitHub, Microsoft)" -p 1 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.1

bd create "Implement backend auth endpoints" -p 1 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.2

bd create "Add frontend login UI components" -p 2 --parent claude-code-plugins-abc
# Returns: claude-code-plugins-abc.3

# Add dependencies (backend must complete before frontend)
bd dep add claude-code-plugins-abc.3 claude-code-plugins-abc.2

# Start with research
bd update claude-code-plugins-abc.1 --status in_progress

Result: Work structured, ready to resume after compaction.

---

Example 2: Tracking Blocked Work

Scenario: Agent discovers API is down during implementation

Agent Actions:

# Mark current task as blocked
bd update claude-code-plugins-xyz --status blocked --notes "API endpoint /auth returns 503, reported to backend team"

# Create blocker task
bd create "Fix /auth endpoint 503 error" -p 0 --type bug
# Returns: claude-code-plugins-blocker

# Link dependency (blocker blocks original task)
bd dep add claude-code-plugins-xyz claude-code-plugins-blocker

# Find other ready work
bd ready
# Shows tasks that aren't blocked - agent can switch to those

Result: Blocked work documented, agent productive on other tasks.

---

Example 3: Session Resume After Compaction

Session 1:

bd create "Implement user authentication" -p 1
bd update myproject-auth --status in_progress
bd update myproject-auth --notes "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting"
# [Conversation compacted - history deleted]

Session 2 (weeks later):

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)

1. Run bd ready first
2. Pick highest priority ready task
3. Run bd show <id> to get full context
4. Update status to in_progress
5. Add notes as you work (critical for compaction survival)

---

Database Selection

bd uses .beads/ directory by default.

Alternate Database:

export BEADS_DIR=/path/to/alternate/beads
bd ready  # Uses alternate database

Multiple Databases: Use BEADS_DIR to switch between projects.

---

Advanced Features

For complex scenarios, see references:

• Compaction Strategies: {baseDir}/references/ADVANCED_WORKFLOWS.md

  • Tier 1/2/ultra compaction for old closed issues
  • Semantic summarization to reduce database size

• Epic Management: {baseDir}/references/ADVANCED_WORKFLOWS.md

  • Nested epics (epics containing epics)
  • Bulk operations on epic children

• Template System: {baseDir}/references/ADVANCED_WORKFLOWS.md

  • Custom issue templates
  • Template variables and defaults

• Git Integration: {baseDir}/references/GIT_INTEGRATION.md

  • Merge conflict resolution
  • Daemon architecture
  • Branching strategies

• Team Collaboration: {baseDir}/references/TEAM_COLLABORATION.md

  • Multi-user workflows
  • Worktree support
  • Prefix strategies

---

Full Documentation

Complete reference: https://github.com/steveyegge/beads

Existing detailed guides:

• {baseDir}/references/CLI_REFERENCE.md - Complete command syntax
• {baseDir}/references/WORKFLOWS.md - Detailed workflow patterns
• {baseDir}/references/DEPENDENCIES.md - Dependency system deep dive
• {baseDir}/references/RESUMABILITY.md - Compaction survival guide
• {baseDir}/references/BOUNDARIES.md - bd vs TodoWrite detailed comparison
• {baseDir}/references/STATIC_DATA.md - Database schema reference

---

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.