Agent-Skills.md

Agent Skills: Beads (br) - Persistent Task Memory for AI Agents

>

UncategorizedID: lambdamechanic/tooltest/beads

Repository

lambdamechanic/tooltest
lambdamechanic
91

Install this agent skill to your local

pnpm dlx add-skill https://github.com/lambdamechanic/tooltest/tree/HEAD/skills/beads

Skill Files

Browse the full folder contents for beads.

Download Skill

Loading file tree…

skills/beads/SKILL.md

Skill Metadata

Name
beads
Description
>

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

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