beads

# 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**: ```bash bd --version # Should return 0.34.0 or later ``` **First-Time Setup** (humans run once): ```bash 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 ```bash 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 ```bash 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 ```bash bd update <task-id> --status in_progress ``` Marks task as actively being worked on. #### Step 5: Add Notes as You Work ```bash 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 ```bash 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**: ```bash bd create "Fix authentication bug" -p 0 --type bug ``` #### Create with Description ```bash bd create "Implement OAuth" -p 1 --description "Add OAuth2 support for Google, GitHub, Microsoft. Use passport.js library." ``` #### Epic with Children ```bash # 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 ```bash bd update <task-id> --status <new-status> ``` **Status Values**: - `open` - Not started - `in_progress` - Actively working - `blocked` - Stuck, waiting on something - `closed` - Completed **Example**: ```bash bd update myproject-abc --status blocked ``` #### Add Progress Notes ```bash bd update <task-id> --notes "Progress update here" ``` **Appends** to existing notes field (doesn't replace). #### Change Priority ```bash bd update <task-id> -p 0 # Escalate to critical ``` #### Add Labels ```bash bd label add <task-id> backend bd label add <task-id> security ``` Labels provide cross-cutting categorization beyond status/type. --- ### Dependency Management #### Add Dependencies ```bash 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**: ```bash # Deployment blocked by tests passing bd dep add deploy-task test-task # test-task blocks deploy-task ``` #### View Dependencies ```bash 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 ```bash bd close <task-id> --reason "Completion summary" ``` **Best Practice**: Always include a reason describing what was accomplished. **Example**: ```bash bd close myproject-abc --reason "Completed: OAuth endpoints implemented with Google, GitHub providers. Tests passing." ``` #### Check Newly Unblocked Work After closing a task, run: ```bash bd ready ``` Closing a task may unblock dependent tasks, making them newly ready. #### Close Epics When Children Complete ```bash bd epic close-eligible ``` Automatically closes epics where all child tasks are closed. --- ### Git Sync Workflow #### All-in-One Sync ```bash 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 ```bash bd export -o backup.jsonl ``` Creates JSONL backup without git operations. #### Import Only ```bash bd import -i backup.jsonl ``` Imports JSONL file into database. #### Background Daemon ```bash 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 ```bash bd ready ``` Shows tasks with no open blockers. #### List All Tasks ```bash 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 ```bash bd show <task-id> ``` Full details: description, dependencies, audit trail, metadata. #### Search by Text ```bash bd search "authentication" # Search titles and descriptions bd search login --status open # Combine with filters ``` #### Find Blocked Work ```bash bd blocked ``` Shows all tasks that have open blockers preventing them from being worked on. #### Project Statistics ```bash 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" |