beads

Track issues in a git-backed store with dependency graphs and notes.

1|1|Updated Jun 2, 2025

Search Tags:#workflow #dependencies #beads #bd #compaction #issue-tracking

Ready to run

npx skills add https://github.com/BumpyClock/dotfiles --skill beads-bumpyclock

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: beads
Source: https://github.com/BumpyClock/dotfiles/tree/main/.ai_agents/skills/beads
Command: npx skills add https://github.com/BumpyClock/dotfiles --skill beads-bumpyclock

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Beads provides a git-backed issue tracker that persists across conversation compaction, enabling durable multi-session work with visible dependencies and a persistent notes history.

Core Features & Use Cases

Git-backed, persistent issue tracking for multi-session projects
Dependency graphs (blocks, related, parent-child, discovered-from) and ready-state surface
Notes/logs and design/acceptance tracking to preserve context across sessions
Seamless integration with other skills and workflows (TodoWrite, writing-plans)
Recovery from compaction and session handoffs

Quick Start

Start by selecting an open issue with bd ready, switch it to in_progress to begin work, and ensure changes persist by running a final sync.

Frequently Asked Questions about beads

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

FAQPage Schema

How do I preserve issue tracking context across conversation compaction?▼

To preserve issue tracking context across conversation compaction, use a git-backed tracker that persists dependency graphs, notes, and design decisions outside the active session window. This ensures history survives compaction and is available for future recovery.

What is the best way to manage multi-session project dependencies with git?▼

Managing multi-session project dependencies with git involves storing dependency graphs and ready-state discovery in a persistent repository. This unblocks progress by keeping blocked, related, and parent-child relationships visible across different working sessions.

How do I start working on an open issue using bd beads?▼

To start working on an open issue, select one from the ready-state surface, switch its status to in_progress to begin work, and run a final sync to ensure all changes and notes persist to the git-backed history.

Can I use git-backed issue tracking alongside TodoWrite and writing-plans workflows?▼

Git-backed issue tracking integrates seamlessly with TodoWrite and writing-plans workflows. It coordinates complex workflows by storing notes, design decisions, and resource references, acting as a durable context layer for these planning tools.

Does conversation compaction lose dependency graph history for long-running projects?▼

Conversation compaction does not lose dependency graph history when using a git-backed tracker. The system captures robust history in notes, design decisions, and resource references, enabling full recovery from compaction and seamless session handoffs.