MCPInstall

beads

by johnlindquistCode Quality & Workflow

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

Installs
79
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/johnlindquist/claude --skill beads
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads beads automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Beads Issue Tracker

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

Prerequisites

Install beads:

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

Initialize in a project:

bd init

CLI Reference

View Ready Work

# 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

# 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

# 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

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

List Issues

# 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

bd show issue-id --json

Dependencies

# 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

# Sync issues to git remote
bd sync

Hygiene Commands

# 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

# Auto-sync on commit
bd hooks install

System Info

# Check version
bd --version

# Project info
bd info --json

Workflow Patterns

Session Start

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

Working on a Task

# 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

# 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

# Sync to git
bd sync

Worktree Mode

When using git worktrees, disable the daemon:

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

FAQ

What does the beads skill do?

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

How do I install beads?

Run npx skills add https://github.com/johnlindquist/claude --skill beads in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/beads/ (personal) or .claude/skills/beads/ (project).

Which AI agents can use beads?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is beads safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains beads?

It is published by johnlindquist in johnlindquist/claude. It has 79 recorded installs.

More from johnlindquist/claude

View all →

gemini-image

johnlindquist/claude

Analyze images using Gemini's vision capabilities. Use for image analysis, text extraction from screenshots, and visual content understanding.

Media & Creative1.2K installs

memory

johnlindquist/claude

Persistent knowledge storage using basic-memory CLI. Use to save notes, search memories semantically, and build context for topics across sessions.

Docs & Writing362 installs

raycast-extension

johnlindquist/claude

Open the skill to read its SKILL.md instructions.

321 installs

brainstorm

johnlindquist/claude

Generate ideas and explore possibilities with AI. Use for creative problem solving, generating alternatives, and expanding on concepts.

Code Quality & Workflow292 installs

deepwiki

johnlindquist/claude

Query DeepWiki for repository documentation and structure. Use to understand open source projects, find API docs, and explore codebases.

Docs & Writing269 installs

think

johnlindquist/claude

Deep multi-framework reasoning using Gemini. Use for complex problem analysis, challenging ideas, and evaluating multiple options with structured thinking.

AI & Agents258 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs