Agent skill

beads

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.

View SKILL.md on GitHub Repository
Stars 10
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/lambdamechanic/tooltest/tree/main/skills/beads

SKILL.md

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

lambdamechanic/tooltest

lambda-workflow

One lifecycle for Lambda repos: choose a br issue, start work, land the PR, and watch GitHub via Dumbwaiter MCP until it merges.

10 1
Explore
lambdamechanic/tooltest

testing-patterns

Testing patterns and standards for this codebase, including async effects, fakes vs mocks, and property-based testing.

10 1
Explore
lambdamechanic/tooltest

tooltest-fix-loop

Use when running tooltest to validate MCP servers, interpret failures, and iterate fixes in this repo.

10 1
Explore
lambdamechanic/tooltest

rust-guidelines

Pragmatic Rust conventions to keep code readable, testable, and performant for this project.

10 1
Explore
lambdamechanic/tooltest

galahad

how to approach tests, types and coverage

10 1
Explore
lambdamechanic/tooltest

bd-to-br-migration

Migrate docs from bd (beads) to br (beads_rust). Use when updating AGENTS.md, converting bd commands, "bd sync" → "br sync --flush-only", or beads migration.

10 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results