beads

# Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction.

## Overview

**bd (beads)** replaces markdown task lists with a dependency-aware graph stored in git.

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

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

## Prerequisites

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

---

## Session Protocol

### Start of Session

```bash
bd ready                              # Find unblocked work
bd show <id>                          # Get full context
bd update <id> --status in_progress   # Claim it
```

### During Work

```bash
bd update <id> --notes "COMPLETED: X. IN PROGRESS: Y. BLOCKED BY: Z"
```

**Critical**: Write notes as if explaining to a future agent with zero context.

### End of Session

```bash
bd close <id> --reason "What was accomplished"
bd sync                               # Sync to git
```

---

## Essential Commands (Top 10)

| Command | Purpose |
|---------|---------|
| `bd ready` | Show unblocked tasks |
| `bd create "Title" -p 1` | Create task (priority 0-4) |
| `bd show <id>` | View task details |
| `bd update <id> --status in_progress` | Start working |
| `bd update <id> --notes "Progress"` | Add notes |
| `bd close <id> --reason "Done"` | Complete task |
| `bd dep add <child> <parent>` | Add dependency |
| `bd list` | See all tasks |
| `bd search <query>` | Find by keyword |
| `bd sync` | Sync with git |

**Full command reference**: `references/CLI_REFERENCE.md`

---

## Task Creation

```bash
# Basic task
bd create "Fix authentication bug" -p 0 --type bug

# With description
bd create "Implement OAuth" -p 1 --description "Add OAuth2 for Google, GitHub"

# Epic