# beads

> Git-backed issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction.

- Author: mark-a-12
- Repository: mark-a-12/panels
- Version: 20260126021713
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/mark-a-12/panels
- Web: https://mule.run/skillshub/@@mark-a-12/panels~beads:20260126021713

---

---
name: beads
description: Git-backed issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction.
---

# Beads (bd) - Git-Backed Issue Tracker

Use the `bd` CLI for managing work that spans sessions, has dependencies, or needs to persist across conversation compaction.

## When to Use Beads

**Use `bd` for:**
- Work spanning multiple sessions
- Tasks with dependencies or blockers
- Complex multi-step implementations
- Discovered work that needs tracking
- Epics with child tasks
- Work requiring context recovery after compaction

**Use TodoWrite for:**
- Simple single-session tasks
- Quick in-conversation tracking
- No persistence needed

## Essential Commands

### Finding Work

```bash
bd ready --json              # Show issues ready to work (no blockers)
bd list --status=open        # All open issues
bd list --status=in_progress # Active work
bd show <id>                 # Detailed view with dependencies
bd blocked                   # Show blocked issues
bd stats                     # Project statistics
```

### Creating Issues

```bash
# Basic creation
bd create "Title" -t <type> -p <priority>

# Types: bug | feature | task | epic | chore
# Priority: 0-4 (0=critical, 1=high, 2=medium, 3=low, 4=backlog)

# Examples
bd create "Fix auth bug" -t bug -p 1
bd create "Add export feature" -t feature -p 2 --description="Export reports as PDF"
bd create "Epic: OAuth Implementation" -t epic -p 0

# With labels
bd create "Update CI config" -t task -l "ci,infrastructure"
```

### Epics with Children

```bash
# Create epic
bd create "Epic: Auth System" -t epic -p 0
# Returns: bd-abc123

# Create child tasks
bd create "Research OAuth providers" -p 1 --parent bd-abc123
bd create "Implement backend endpoints" -p 1 --parent bd-abc123
bd create "Add frontend login UI" -p 2 --parent bd-abc123
```

### Dependencies

```bash
# Add dependency (issue depends on depends-on)
bd dep add <issue-id> <depends-on-id>

# Dependency types
bd dep add bd-child bd-parent --type blocks        # Blocking
bd dep add bd-child bd-parent --type parent-child  # Hierarchy
bd dep add bd-bug bd-feature --type discovered-from # Discovered work
```

### Updates and Closing

```bash
bd update <id> --status=in_progress  # Claim work
bd update <id> --assignee=username   # Assign
bd close <id>                        # Close single
bd close <id1> <id2> <id3>           # Close multiple (efficient)
bd close <id> --reason="Completed"   # Close with reason
```

### Labels

```bash
bd label add <id> security           # Add label
bd list --label backend,auth         # AND filter
bd list --label-any frontend,backend # OR filter
```

### Sync

```bash
bd sync          # Force immediate sync (CRITICAL at session end)
bd doctor        # Check for issues
bd doctor --fix  # Auto-fix problems
```

## Session Workflow

### Start
```bash
bd prime         # Load context (auto on session start)
bd ready --json  # Find available work
bd show <id>     # Review details
bd update <id> --status=in_progress  # Claim
```

### End (CRITICAL)
```bash
bd close <completed-ids>    # Close finished work
bd sync                     # Force sync before ending
git push                    # Push code (beads auto-synced)
```

## Context Recovery

After compaction or new session:
```bash
bd prime                     # Reload workflow context
bd list --status=in_progress # See active work
bd show <id>                 # Full context
```

For detailed CLI reference, see [CLI_REFERENCE.md](references/CLI_REFERENCE.md).