Stats
Actions
Tags
From workflow-tools
Guide for using Beads (bd/beads), a local-first issue tracker that stores issues as plain text files. Use when managing project issues, tracking work across sessions, or following issue-tracking workflows.
How this skill is triggered — by the user, by Claude, or both
Slash command
/workflow-tools:beads-issue-trackerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Beads is a minimalist, local-first issue tracker that stores issues as plain text files in a `.beads/` directory. It provides simple, file-based issue tracking without external dependencies, integrates seamlessly with git workflows, and works offline.
Beads is a minimalist, local-first issue tracker that stores issues as plain text files in a .beads/ directory. It provides simple, file-based issue tracking without external dependencies, integrates seamlessly with git workflows, and works offline.
| Command | Description |
|---|---|
bd list / beads list | List open issues |
bd list --all | List all issues including closed |
bd list --status open | Filter by status |
bd list --label TAG | Filter by label |
bd show N | Display issue #N |
bd ready | Show issues with no blockers |
bd create --title="..." --type=TYPE --priority=N --label="x,y" | Create new issue |
bd update N --status STATUS | Update issue status |
bd close N / bd close N -r "reason" | Close issue |
bd comment N "Text" | Add comment to issue |
bd search "term" | Search issues |
bd sync | Sync with git |
bd prime | Get compact usage examples |
bd onboard | Get started guide |
| Type | Usage |
|---|---|
epic | Large body of work containing multiple children |
feature | New functionality being added |
task | Generic work item, often implementation work |
bug | Something broken that needs fixing |
chore | Maintenance, cleanup, refactoring |
merge-request | PR/MR tracking |
Priority uses numeric values 0-4 (or P0-P4). Do NOT use "high"/"medium"/"low":
| Priority | Meaning |
|---|---|
| 0 / P0 | Critical - drop everything |
| 1 / P1 | High - do next |
| 2 / P2 | Medium - normal work |
| 3 / P3 | Low - when time permits |
| 4 / P4 | Backlog - someday/maybe |
bd ready # Show issues with no blockers
bd list --status=open # All open issues
bd show <id> # View issue details, description, and history
bd update <id> --status in_progress # Claim work
# ... do the work ...
bd close <id> -r "Implemented feature X" # Complete work
bd update <id> --status open # Release the issue
bd create --title="Add params support" --type=feature --priority=2 --label="api,core"
At the end of each session:
bd list --status openbd close N -r "reason"bd comment N "In progress: completed X, next is Y"bd create --title="Follow-up task" ...bd comment N "Decided approach A because of constraint B"bd list should show accurate project stategit add .beads/ && git commit.beads/issues.jsonl manually - always use bd commandsin_progress at a time per epicbug, feature, enhancement, docs, refactor, testapi, database, frontend, infra, cli, corenpx claudepluginhub code0100fun/botfiles --plugin workflow-toolsLocal-first issue tracker for AI agents using beads_rust. Track tasks, manage dependencies, find ready work, sync issues to git via JSONL.
Decomposes GitHub issues into structured Beads epics, tasks, and sub-tasks with objectively verifiable acceptance criteria and dependencies. Useful for planning actionable work in Beads projects.
Guides using Beads (bd) distributed git-backed issue tracker for task management, dependency tracking, AI agent workflows, and multi-branch parallel development.