Skill

Beads (beads-2)

Dolt-powered 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. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or…

Type: Skill
Repository: gastownhall/beads
GitHub stars: 27.5k
License: MIT
Repo last updated: Sep 27, 2026
Source file: plugins/beads/skills/beads/SKILL.md
Version: 0.60.0
Author: Steve Yegge <[email protected]>

What Beads (beads-2) is

Beads (beads-2) is a skill published in the gastownhall/beads repository on GitHub, which has about 27.5k stars. The repository describes itself as: “Beads - A memory upgrade for your coding agent”

A skill is a folder with a SKILL.md file: frontmatter with a name and a description, followed by instructions Claude follows. Claude loads a skill automatically when a task matches its description, and you can also run it directly with a slash and its name.

Skills work in Claude Code and in Claude Cowork, which makes Beads a portable way to give Claude the same method everywhere.

How to install Beads (beads-2)

Claude Code

Download the beads folder from the repository.
Save it as ~/.claude/skills/<skill-name>/SKILL.md for all projects, or .claude/skills/<skill-name>/SKILL.md for one project.
Claude loads it automatically when a task matches; you can also run it with / and its name.

Claude Cowork

Zip the skill folder so SKILL.md sits at the top level of the folder.
Open Customize → Skills, click +, then upload the ZIP.
Start a task that matches the description, or call it by name with /.

New to extending Cowork? Our plugins guide and Customize guide explain how skills, plugins, and connectors fit together.

Inside the source file

An excerpt from plugins/beads/skills/beads/SKILL.md, shared under the repository's MIT license. Read the full file on GitHub.

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.

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 --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 — Get full context
bd update --claim — Claim and start work atomically
Add notes as you work (critical for compaction survival)
bd close --reason "..." — Complete task
bd dolt push — Push to Dolt remote (if configured)

Output

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

Error Handling

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 --long

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

Advanced Features

Resources

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).

Before you install

Read the whole file first. Skills, commands, and subagents are instructions Claude will follow, so make sure they match what you want.
Check which tools, scripts, or MCP servers it uses. Local servers and scripts run with your permissions.
Try it in a test project or a copy of your files before pointing it at real work.
Pin the version you tested, and review changes before updating.
Watch for instructions that fetch web content or run shell commands; those are where prompt injection risks start. See our prompt injection guide.

FAQ

What is Beads (beads-2)?

Beads (beads-2) is a skill for Claude Code and Claude Cowork from the gastownhall/beads repository on GitHub. Dolt-powered 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. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or…

How do I install Beads (beads-2) in Claude Code?

Download the beads folder from the repository. Save it as ~/.claude/skills/<skill-name>/SKILL.md for all projects, or .claude/skills/<skill-name>/SKILL.md for one project. Claude loads it automatically when a task matches; you can also run it with / and its name.

Can I use Beads (beads-2) in Claude Cowork?

Zip the skill folder so SKILL.md sits at the top level of the folder. Open Customize → Skills, click +, then upload the ZIP. Start a task that matches the description, or call it by name with /.

Is Beads (beads-2) safe to install?

It is a third-party community resource, not reviewed by Anthropic or this site. Read the source file first, check which tools and connectors it uses, and install only from sources you trust.

Similar resources

Browse all skills, subagents, and plugins →

Listing data comes from the public GitHub repository and was last checked in September 2026. Excerpts are © their authors and shared under MIT. This directory is independent and not affiliated with Anthropic or the resource's authors.