Agent skill

beads

Track tasks and issues using the bd CLI. Use for task management, sprint planning, dependency tracking, and project organization. Replaces TodoWrite.

View SKILL.md on GitHub Repository
Stars 21
Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/beads

SKILL.md

Beads Issue Tracker

Git-backed issue tracking with dependency awareness. Perfect for agent task management.

Prerequisites

Install beads:

bash
# Install via cargo or download binary
cargo install beads
# Or download from releases

Initialize in a project:

bash
bd init

CLI Reference

View Ready Work

bash
# Get issues with no blockers
bd ready --json

# Filter by assignee
bd ready --assignee username --json

# Filter by label
bd ready --label "urgent" --json

# Limit results
bd ready --limit 5 --json

Create Issues

bash
# Basic task
bd create "Task title" --json

# With details
bd create "Task title" -d "Description" -t task -p 2 --json

# As subtask of epic
bd create "Subtask" --parent epic-123 --force --json

# With dependencies
bd create "Task" --deps "other-issue-id" --json

# Quick mode (less output)
bd create "Task" -q --json

Issue Types

  • bug - Bug reports
  • feature - New features
  • task - General tasks
  • epic - Parent containers
  • chore - Maintenance work

Priority Levels

  • 0 - Critical
  • 1 - High
  • 2 - Normal (default)
  • 3 - Low
  • 4 - Backlog

Update Issues

bash
# Change status
bd update issue-id -s in_progress --json

# Add notes
bd update issue-id --notes "Progress update" --json

# Change priority
bd update issue-id -p 1 --json

# Add labels
bd update issue-id --add-label "urgent" --json

Close Issues

bash
# Close with reason
bd close issue-id -r "Completed successfully" --json

List Issues

bash
# All open issues
bd list --status open --json

# Filter by type
bd list --type bug --json

# Filter by assignee
bd list --assignee "username" --json

# Filter by label
bd list --label "backend" --json

# Filter by priority
bd list --priority 1 --json

Show Issue Details

bash
bd show issue-id --json

Dependencies

bash
# Add dependency (issue-a depends on issue-b)
bd dep add issue-a issue-b

# Dependency types: blocks, related, parent-child, discovered-from
bd dep add issue-a issue-b -t blocks

Sync with Git

bash
# Sync issues to git remote
bd sync

Hygiene Commands

bash
# Find duplicate issues
bd duplicates --dry-run

# Auto-merge duplicates
bd duplicates --auto-merge

# Find stale issues (no activity)
bd stale --days 14 --json

# Cleanup old closed issues
bd cleanup --dry-run
bd cleanup -f

Install Git Hooks

bash
# Auto-sync on commit
bd hooks install

System Info

bash
# Check version
bd --version

# Project info
bd info --json

Workflow Patterns

Session Start

bash
# See what's ready to work on
bd ready --json

Working on a Task

bash
# Start working
bd update task-id -s in_progress --json

# Add progress notes
bd update task-id --notes "Halfway done" --json

# Complete
bd close task-id -r "Implemented and tested" --json

Epic Planning

bash
# Create epic
bd create "User Authentication" -t epic --json

# Add subtasks
bd create "Design auth flow" --parent auth-epic --force --json
bd create "Implement login" --parent auth-epic --force --json
bd create "Add tests" --parent auth-epic --force --json

# Add dependencies between subtasks
bd dep add implement-id design-id -t blocks
bd dep add tests-id implement-id -t blocks

End of Session

bash
# Sync to git
bd sync

Worktree Mode

When using git worktrees, disable the daemon:

bash
export BEADS_NO_DAEMON=1
# Or per-command
bd --no-daemon ready --json

Best Practices

  1. Always use --json for parseable output
  2. Use bd ready at session start to see unblocked work
  3. Add dependencies to express task relationships
  4. Use epics for grouping related tasks
  5. Run bd sync before ending sessions
  6. Install hooks for automatic sync: bd hooks install

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

johnlindquist/claude

testgen

Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.

21 5
Explore
johnlindquist/claude

article

Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.

21 5
Explore
johnlindquist/claude

packx

Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.

21 5
Explore
johnlindquist/claude

long-agent

Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.

21 5
Explore
johnlindquist/claude

db

Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.

21 5
Explore
johnlindquist/claude

investigate

Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.

21 5
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results