beads

---
name: beads
description: >
  Dolt-powered 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. Trigger with "create task", "what's
  ready", "track this work", "resume after compaction". Make sure to use this skill
  whenever managing multi-session work, tracking dependencies, or recovering context.
allowed-tools: "Read,Bash(bd:*)"
version: "0.60.0"
author: "Steve Yegge <steve.yegge@gmail.com>"
license: "MIT"
compatible-with: [claude-code, codex]
tags: [issue-tracking, task-management, multi-session, dependencies]
---

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

## bd vs TodoWrite

**Decision test**: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.

| bd (persistent) | TodoWrite (ephemeral) |
|-----------------|----------------------|
| Multi-session, dependencies, compaction survival | Single-session linear tasks |
| Dolt-backed team sync | Conversation-scoped |

See [BOUNDARIES.md](resources/BOUNDARIES.md) for detailed comparison.

## Prerequisites

```bash
bd --version  # Requires v0.60.0+
```

- **bd CLI** installed and in PATH
- **Git repository** (optional — use `BEADS_DIR` + `--stealth` for git-free operation)
- **Initialization**: `bd init` run once (humans do this, not agents)

## CLI Reference

**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).
**Run `bd <command> --help`** for specific command usage.

Essential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd dolt push`

## Session Protocol

1. `bd ready` — Find unblocked work
2. `bd show <id>` — Get full context
3. `bd update <id> --claim` — Claim and start work atomically
4. Add notes as you work (critical for compaction survival)
5. `bd close <id> --reason "..."` — Complete task
6. `bd dolt push` — Push to Dolt remote (if configured)

## Output

Append `--json` to any command for structured output. Use `bd show <id> --long` for extended metadata. Status icons: `○` open `◐` in_progress `●` blocked `✓` closed `❄` deferred.

## Error Handling

| Error | Fix |
|-------|-----|
| `database not found` | `bd init <prefix>` in project root |
| `not in a git repository` | `git init` first |
| `disk I/O error (522)` | Move `.beads/` off cloud-synced filesystem |
| Status updates lag | Use server mode: `bd dolt start` |

See [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) for full details.

## Examples

**Track a multi-session feature:**
```bash
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json
```

**Recover after compaction:** `bd list --status in_progress --json` then `bd show <id> --long`

**Discover work mid-task:** `bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json`

## Advanced Features

| Feature | CLI | Resource |
|---------|-----|----------|
| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |
| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |
| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |
| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |
| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |

## Resources

| Category | Files |
|----------|-------|
| **Getting Started** | [BOUNDARIES.md](resources/BOUNDARIES.md), [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) (live reference pointers), [WORKFLOWS.md](resources/WORKFLOWS.md) |
| **Core Concepts** | [DEPENDENCIES.md](resources/DEPENDENCIES.md), [ISSUE_CREATION.md](resources/ISSUE_CREATION.md), [PATTERNS.md](resources/PATTERNS.md) |
| **Resilience** | [RESUMABILITY.md](resources/RESUMABILITY.md), [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) |
| **Advanced** | [MOLECULES.md](resources/MOLECULES.md), [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md), [AGENTS.md](resources/AGENTS.md), [ASYNC_GATES.md](resources/ASYNC_GATES.md), [WORKTREES.md](resources/WORKTREES.md) |
| **Reference** | [STATIC_DATA.md](resources/STATIC_DATA.md), [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) |

## Validation

If `bd --version` reports newer than `0.60.0`, this skill may be stale. Run `bd prime` for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth ([ADR-0001](adr/0001-bd-prime-as-source-of-truth.md)).

• CLAUDE.md 3 KB
• README.md 5 KB
• SKILL.md 5 KB
• adr/0001-bd-prime-as-source-of-truth.md 2 KB
• agents/openai.yaml 1 KB
• commands/audit.md 1 KB
• commands/blocked.md 1 KB
• commands/close.md 1 KB
• commands/comments.md 1 KB
• commands/compact.md 1 KB
• commands/create.md 1 KB
• commands/decision.md 3 KB
• commands/delete.md 1 KB
• commands/dep.md 3 KB
• commands/epic.md 1 KB
• commands/export.md 1 KB
• commands/import.md 4 KB
• commands/init.md 1 KB
• commands/label.md 1 KB
• commands/list.md 3 KB
• commands/prime.md 1 KB
• commands/quickstart.md 1 KB
• commands/ready.md 1 KB
• commands/rename-prefix.md 1 KB
• commands/reopen.md 1 KB
• commands/restore.md 1 KB
• commands/search.md 3 KB
• commands/show.md 1 KB
• commands/stats.md 1 KB
• commands/sync.md 5 KB
• commands/template.md 6 KB
• commands/update.md 1 KB
• commands/version.md 1 KB
• commands/workflow.md 2 KB
• resources/AGENTS.md 2 KB
• resources/ASYNC_GATES.md 6 KB
• resources/BOUNDARIES.md 17 KB
• resources/CHEMISTRY_PATTERNS.md 7 KB
• resources/CLI_REFERENCE.md 1 KB
• resources/DEPENDENCIES.md 19 KB
• resources/INTEGRATION_PATTERNS.md 13 KB
• resources/ISSUE_CREATION.md 5 KB
• resources/MOLECULES.md 10 KB
• resources/PATTERNS.md 11 KB
• resources/RESUMABILITY.md 5 KB
• resources/STATIC_DATA.md 2 KB
• resources/TROUBLESHOOTING.md 13 KB
• resources/WORKFLOWS.md 19 KB
• resources/WORKTREES.md 4 KB