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:

• 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"

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)

• Run bd ready first

• Pick highest priority ready task

• Run bd show <id> to get full context

• Update status to in_progress

• 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.