Beads is a Dolt-powered issue tracker that helps manage tasks across multiple sessions while preserving context and handling dependencies.

How does Beads differ from other task managers?

Unlike traditional task managers that focus on single-session tasks, Beads allows for multi-session tracking and is designed to maintain context even after conversation compaction.

What are the essential commands in Beads?

Key commands include `bd create` for creating tasks, `bd update` for updating task status, and `bd close` for completing tasks.

Is there a graphical interface for Beads?

No, Beads operates entirely through a command-line interface, which may not be suitable for users who prefer graphical tools.

What are the prerequisites for using Beads?

You need to have the `bd` CLI installed and in your PATH, and you should run `bd init` to set it up before use.

Beads

Name: Beads
Availability: InStock
Author: gastownhall

Free

Persistent task management for multi-session workflows.

by gastownhall26.2k stars on gastownhall/beads

1 views

Updated Aug 11, 2026

Get this skill

Free · Opens the source repo

What Beads does

Beads is a Dolt-powered issue tracker designed for developers and teams who need to manage tasks across multiple sessions while maintaining context and handling dependencies. Unlike traditional task managers that operate on a single session basis, Beads allows users to create, track, and manage tasks that can span days or weeks, ensuring that important details are preserved even after conversation compaction. This is particularly useful in environments where tasks are complex and interdependent, requiring a robust system to keep everything organized.

The skill utilizes a graph-based structure to represent tasks and their relationships, allowing users to easily visualize dependencies and track progress. With commands like bd create, bd update, and bd close, users can efficiently manage their workflow while ensuring that all relevant information is captured. The integration with Dolt provides a unique advantage, enabling team synchronization and version control for task data, which is essential when collaborating with others.

Beads is particularly suited for developers working on long-term projects or those who frequently switch between tasks. By using commands such as bd ready to find unblocked work or bd show to retrieve full context on a task, users can maintain a clear overview of their workload. The CLI interface is straightforward, making it accessible for users familiar with command-line tools. Additionally, the ability to append --json to commands allows for structured output, which can be integrated into other tools or scripts for further automation.

Overall, Beads is an effective solution for anyone needing a persistent memory system for task management that survives beyond individual sessions, making it a valuable addition to any developer's toolkit.

When to use it

Use Beads when managing tasks that require context recovery after compaction or when working on projects with multiple dependencies that span over time.

When not to use it

Beads may not be suitable for simple, one-off tasks that do not require long-term tracking or for users who prefer a graphical user interface over a command-line tool.

What you can build with it

Track a Multi-Session Feature

Create tasks for features that span several sessions, ensuring all dependencies are tracked and context is preserved.

Recover After Compaction

Use Beads to list in-progress tasks and recover context after a session has been compacted.

Manage Dependencies in Projects

Utilize Beads to handle complex project dependencies, ensuring that tasks are completed in the correct order.

How to install Beads

View source

1. Install with the skills CLI

npx skills add gastownhall/beads/beads --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by gastownhall

Beads - Persistent Task Memory for AI Agents

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

bd vs TodoWrite

Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.

bd (persistent)	TodoWrite (ephemeral)
Multi-session, dependencies, compaction survival	Single-session linear tasks
Dolt-backed team sync	Conversation-scoped

See BOUNDARIES.md for detailed comparison.

Prerequisites

bd --version  # Requires v0.60.0+

bd CLI installed and in PATH
Git repository (optional — use BEADS_DIR + --stealth for git-free operation)
Initialization: bd init run once (humans do this, not agents)

CLI Reference

Run bd prime for AI-optimized workflow context (auto-loaded by hooks). Run bd <command> --help for specific command usage.

Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push

Session Protocol

bd ready — Find unblocked work
bd show <id> — Get full context
bd update <id> --claim — Claim and start work atomically
Add notes as you work (critical for compaction survival)
bd close <id> --reason "..." — Complete task
bd dolt push — Push to Dolt remote (if configured)

Output

Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.

Error Handling

Error	Fix
`database not found`	`bd init <prefix>` in project root
`not in a git repository`	`git init` first
`disk I/O error (522)`	Move `.beads/` off cloud-synced filesystem
Status updates lag	Use server mode: `bd dolt start`

See TROUBLESHOOTING.md for full details.

Examples

Track a multi-session feature:

bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json

Recover after compaction: bd list --status in_progress --json then bd show <id> --long

Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json

Advanced Features

Feature	CLI	Resource
Molecules (templates)	`bd mol --help`	MOLECULES.md
Chemistry (pour/wisp)	`bd pour`, `bd wisp`	CHEMISTRY_PATTERNS.md
Agent beads	`bd agent --help`	AGENTS.md
Async gates	`bd gate --help`	ASYNC_GATES.md
Worktrees	`bd worktree --help`	WORKTREES.md

Resources

Category	Files
Getting Started	BOUNDARIES.md, CLI_REFERENCE.md (live reference pointers), WORKFLOWS.md
Core Concepts	DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md
Resilience	RESUMABILITY.md, TROUBLESHOOTING.md
Advanced	MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md
Reference	STATIC_DATA.md, INTEGRATION_PATTERNS.md

Validation

If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).

Frequently asked questions about Beads

Similar skills

Daily Focus Board

A motivating tool for daily task management and focus.

Paperclip

Streamline task coordination with Paperclip API.

Context Agent

Enhance session continuity with automatic context management.

Garden Inbox

Efficiently clean up your Paperclip inbox with ease.

Daily Sales Briefing

Start your day with a prioritized sales briefing.

Update Command

Keep your tasks and memory in sync effortlessly.

Details

Category: Productivity
Subcategory: Task Management
Type: workflow
Level: intermediate
Licence: MIT
Bundled files: 48

Works with

Claude Code Claude API Codex CLI Cursor Google Antigravity GitHub Copilot Windsurf OpenCode Cline Roo Code Goose Kiro Continue Trae

New to skills?

How to install any agent skill

One folder, every agent. The exact install path for Claude Code, Codex, Cursor, Antigravity and more.

Read the guide

Requirements

Shell access

Source

This skill is published by gastownhall on GitHub. We link to the original and do not re-host it.

gastownhall/beads

What's included

CLAUDE.md

README.md

SKILL.md

adr/0001-bd-prime-as-source-of-truth.md

agents/openai.yaml

commands/audit.md

commands/blocked.md

commands/close.md

commands/comments.md

commands/compact.md

commands/create.md

commands/decision.md

commands/delete.md

commands/dep.md

commands/epic.md

commands/export.md

commands/import.md

commands/init.md

commands/label.md

commands/list.md

commands/prime.md

commands/quickstart.md

commands/ready.md

commands/rename-prefix.md

commands/reopen.md

commands/restore.md

commands/search.md

commands/show.md

commands/stats.md

commands/sync.md

commands/template.md

commands/update.md

commands/version.md

commands/workflow.md

resources/AGENTS.md

resources/ASYNC_GATES.md

resources/BOUNDARIES.md

resources/CHEMISTRY_PATTERNS.md

resources/CLI_REFERENCE.md

resources/DEPENDENCIES.md

resources/INTEGRATION_PATTERNS.md

resources/ISSUE_CREATION.md

resources/MOLECULES.md

resources/PATTERNS.md

resources/RESUMABILITY.md

resources/STATIC_DATA.md

resources/TROUBLESHOOTING.md

resources/WORKFLOWS.md

resources/WORKTREES.md