beads

Persist task context across sessions using Git-backed beads.

4|Updated Jan 15, 2026
One-click install
npx skills add https://github.com/johnnymo87/workstation --skill beads-johnnymo87
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: beads
Source: https://github.com/johnnymo87/workstation/tree/main/assets/claude/skills/beads
Command: npx skills add https://github.com/johnnymo87/workstation --skill beads-johnnymo87

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Beads provides a Git-backed memory system to preserve task context across sessions, ensuring work survives compaction and session boundaries.

Core Features & Use Cases

  • Git-backed memory that persists across sessions and compaction.
  • Supports creation, updating, and linking of beads with dependencies (blocks, discovered-from, parent-child, related).
  • Designed for handoff and long-running projects, capturing decisions, blockers, and outcomes for future reference.

Quick Start

To begin, surface ready beads work with the bd ready command, create beads for ongoing tasks using bd create, and update beads notes as decisions and progress occur. Then use bd sync to persist changes.

Frequently Asked Questions about beads

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I persist task context across Git sessions without losing work during compaction?

Beads provides Git-backed memory that survives session boundaries and compaction by storing task context as persistent records. Use bd create to capture ongoing work, bd ready to surface actionable tasks, and bd sync to persist changes to Git, ensuring your project state and decisions remain accessible across long sessions.

Can I track dependencies and blockers across multiple related tasks in a long-running project?

Yes. Beads supports linking beads with dependency relationships including blocks, discovered-from, parent-child, and related connections. This enables you to map blockers, trace discovery chains, and maintain visibility across interconnected work items throughout complex projects.

What's the best way to document decisions and blockers so they survive context loss between sessions?

Create beads for each decision point or blocker using bd create, update notes as progress occurs with bd update, and sync to Git via bd sync. Beads stores these annotations persistently, making them retrievable for future sessions and handoffs without manual re-entry.

How do I manage task memory for knowledge work or projects that span multiple working sessions?

Beads is designed for multi-session knowledge work and long-running initiatives. Surface ready work with bd ready, create beads for new tasks, link them by dependency type, annotate decisions and blockers, then sync—building a persistent, Git-backed record that outlives individual sessions.

Do I need version control setup before using task memory across sessions?

Yes. Beads requires Git as its backing store to persist task context across sessions and compaction. Ensure your project is initialized in a Git repository; beads will store memory records there, making them durable and accessible across workspace boundaries.

What limitations should I know about storing task dependencies and multi-session state?

Beads' Git-backed approach is durable but scales with project complexity. It excels at capturing decisions and blockers for handoffs and long-running work, but manual linking and note discipline are required—automation of inference or conflict resolution across complex dependency graphs is not built in.