beads

Original source / Raw SKILL.md

---
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.
allowed-tools: "Read,Bash(br:*)"
version: "0.43.0"
author: "Steve Yegge <https://github.com/steveyegge>"
license: "MIT"
---

# Beads (br) - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

## br vs TodoWrite

| br (persistent) | TodoWrite (ephemeral) |
|-----------------|----------------------|
| Multi-session work | Single-session tasks |
| Complex dependencies | Linear execution |
| Survives compaction | Conversation-scoped |
| Git-backed, team sync | Local to session |

**Decision test**: "Will I need this context in 2 weeks?" -> YES = br

**When to use br**:
- Work spans multiple sessions or days
- Tasks have dependencies or blockers
- Need to survive conversation compaction
- Exploratory/research work with fuzzy boundaries
- Collaboration with team (git sync)

**When to use TodoWrite**:
- Single-session linear tasks
- Simple checklist for immediate work
- All context is in current conversation
- Will complete within current session

## Prerequisites

```bash
br version
```

- **br CLI** installed and in PATH
- **Git repository** (br stores issues in SQLite, exports to JSONL for git)
- **Fresh clone**: If `.beads/beads.db` is missing, hydrate it from `.beads/issues.jsonl`:
  - `br sync --import-only --db .beads/beads.db`

## CLI Reference

Run `br <command> --help` for specific command usage.

Essential commands: `br ready`, `br create`, `br show`, `br update`, `br close`, `br sync --flush-only`

## Session Protocol

1. `br ready` - Find unblocked work
2. `br show <id>` - Get full context
3. `br update <id> --status in_progress` - Start work
4. Add notes as you work (critical for compaction survival)
5. `br close <id> --reason "..."` - Complete task
6. Export issue changes and commit/push:
   - `br sync --flush-only`
   - `git add .beads/issues.jsonl && git commit -m "Update issues" && git push`

## Full Documentation

- `br --help`
- GitHub: https://github.com/Dicklesworthstone/beads_rust


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# Beads (br) Skill for Claude Code

A skill for using `br` (beads_rust) issue tracking with Claude Code.

## What This Skill Does

This skill teaches Claude Code how to use br effectively for:
- **Multi-session work tracking** - Persistent memory across conversation compactions
- **Dependency management** - Graph-based issue relationships
- **Session handoff** - Writing notes that survive context resets

## Installation

Copy the `beads/` directory to your Claude Code skills location:

```bash
# Global installation
cp -r beads ~/.claude/skills/

# Or project-local
cp -r beads .claude/skills/
```

## When Claude Uses This Skill

The skill activates when conversations involve:
- "multi-session", "complex dependencies", "resume after weeks"
- "project memory", "persistent context", "side quest tracking"
- Work that spans multiple days or compaction cycles
- Tasks too complex for simple TodoWrite lists

## File Structure

```
beads/
├── SKILL.md                 # Main skill file (Claude reads this first)
├── CLAUDE.md                # Maintenance guide for updating the skill
├── README.md                # This file (for humans)
└── resources/               # Legacy reference docs (may not match br feature set)
```

## Key Concepts

### br vs TodoWrite

| Use br when... | Use TodoWrite when... |
|----------------|----------------------|
| Work spans multiple sessions | Single-session tasks |
| Complex dependencies exist | Linear step-by-step work |
| Need to resume after weeks | Just need a quick checklist |
| Knowledge work with fuzzy boundaries | Clear, immediate tasks |

### The Dependency Direction Trap

`br dep add A B` means **"A depends on B"** (B must complete before A can start).

```bash
# Want: "Setup must complete before Implementation"
br dep add implementation setup  # CORRECT
# NOT: br dep add setup implementation  # WRONG
```

### Surviving Compaction

When Claude's context gets compacted, conversation history is lost but br state survives. Write notes as if explaining to a future Claude with zero context:

```bash
br update issue-123 --notes "COMPLETED: JWT auth with RS256
KEY DECISION: RS256 over HS256 for key rotation
IN PROGRESS: Password reset flow
NEXT: Implement rate limiting"
```

## Requirements

- br installed: https://github.com/Dicklesworthstone/beads_rust
- A git repository (issues exported to `.beads/issues.jsonl` for sync)

## License

MIT

```