---
name: Beads
slug: beads
category: AI Engineering
description: Beads provides a durable, shared task-tracking workflow for repositories that use the bd CLI. Use it to find ready work, claim or close tasks, manage blockers, and preserve project context across sessions.
github: "https://github.com/gastownhall/beads/tree/main/internal/templates/skills/beads"
language: Go
stars: 26300
forks: 1773
install: "npx degit https://github.com/gastownhall/beads/tree/main/internal/templates/skills/beads ~/.claude/skills/beads"
installs_to: ~/.claude/skills/beads
source_path: internal/templates/skills/beads/SKILL.md
collection_size: 3
category_size: 2451
collection_url: "https://dirskills.com/collections/gastownhall/beads"
added: 2026-08-14T07:12:00.939Z
last_synced: 2026-08-14T07:12:00.939Z
canonical_url: "https://dirskills.com/skills/beads"
---

# Beads

Beads provides a durable, shared task-tracking workflow for repositories that use the bd CLI. Use it to find ready work, claim or close tasks, manage blockers, and preserve project context across sessions.

**Install:**

```bash
npx degit https://github.com/gastownhall/beads/tree/main/internal/templates/skills/beads ~/.claude/skills/beads
```

## README

# Beads

Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.

## First Step

Run:

```bash
bd prime
```

If that prints nothing, check whether the repository has an active Beads workspace:

```bash
bd where
```

## Preferred Route

Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.

## Core CLI Workflow

1. Find work:

```bash
bd ready
bd list --status=open
bd list --status=in_progress
```

2. Inspect before editing:

```bash
bd show <id>
```

3. Claim work atomically:

```bash
bd update <id> --claim
```

4. Create durable follow-up work when implementation reveals new tasks:

```bash
bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
```

5. Close completed work:

```bash
bd close <id> --reason="Completed"
```

## What Belongs In Beads

Use Beads for:

- shared project tasks
- blockers and dependencies
- discovered follow-up work
- work that must survive thread reset, compaction, or handoff
- status that another person or agent should be able to resume

Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.

## Rules

- Do not create markdown TODO files as the source of truth when Beads is available.
- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
- Prefer `--json` when parsing `bd` output programmatically.
- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
- Do not auto-close or mutate tasks unless the work is actually complete.