beads

---
name: beads
description: Git-backed issue tracker for AI agents. Use when managing tasks, dependencies, or multi-step work. Triggers on task tracking, issue management, dependency graphs, ready work queues, or mentions of "beads" / "bd" CLI.
metadata:
  openclaw:
    emoji: 📿
    requires:
      bins: [bd]
    install:
      - id: brew
        kind: brew
        formula: beads
        bins: [bd]
        label: Install beads (brew)
      - id: npm
        kind: npm
        package: "@beads/bd"
        bins: [bd]
        label: Install beads (npm)
---

# Beads

Distributed, git-backed graph issue tracker for AI agents. Replaces markdown plans with a dependency-aware task graph stored as JSONL in `.beads/`.

## Quick Start

```bash
# Initialize (non-interactive for agents)
bd init --quiet

# Check ready work
bd ready --json

# Create a task
bd create "Complete task X" -p 1 --json

# View task
bd show bd-a1b2 --json
```

## Core Workflow

1. `bd ready --json` — Find unblocked work
2. `bd update <id> --status in_progress` — Claim task
3. Do the work
4. `bd close <id> --reason "Done"` — Complete task
5. `bd sync` — Force sync before ending session

## Agent-Critical Rules

- **Always use `--json`** for machine-readable output
- **Never use `bd edit`** — opens $EDITOR, unusable by agents
- **Use `bd update`** instead: `bd update <id> --title "New title" --description "New desc"`
- **Run `bd sync`** at end of session to flush changes to git

## Commands

### Initialize

```bash
bd init --quiet              # Non-interactive, auto-installs hooks
bd init --prefix myproj      # Custom ID prefix
bd init --stealth            # Local only, don't commit .beads/
bd init --contributor        # Fork workflow (separate planning repo)
```

### Create Issues

```bash
bd create "Title" -p 1 --json                    # Priority 1 (0=critical, 3=low)
bd create "Title" -t epic -p 0 --json            # Create epic
bd create "Subtask" -p 1 --json                  # Under epic: bd-a3f8.1,