beads/PLUGIN.md

Beads Claude Code Plugin

AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple slash commands and MCP tools.

What is Beads?

Beads (bd) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers:

• Track work with a simple CLI
• Discover and link related tasks during development
• Maintain context across coding sessions
• Auto-sync issues via JSONL for git workflows

Installation

Prerequisites

1. Install beads CLI:

curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash

2. Install Python and uv (for MCP server):

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

Install Plugin

There are two ways to install the beads plugin:

Option 1: From GitHub (Recommended)

# In Claude Code
/plugin marketplace add steveyegge/beads
/plugin install beads

Option 2: Local Development

# Clone the repository
git clone https://github.com/steveyegge/beads
cd beads

# Add local marketplace
/plugin marketplace add .

# Install plugin
/plugin install beads

Restart Claude Code

After installation, restart Claude Code to activate the MCP server.

Quick Start

# Initialize beads in your project
/bd-init

# Create your first issue
/bd-create "Set up project structure" feature 1

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

# Show full workflow guide
/bd-workflow

Available Commands

Core Workflow Commands

• /bd-ready - Find tasks with no blockers, ready to work on
• /bd-create [title] [type] [priority] - Create a new issue interactively
• /bd-show [issue-id] - Show detailed information about an issue
• /bd-update [issue-id] [status] - Update issue status or other fields
• /bd-close [issue-id] [reason] - Close a completed issue

Project Management

• /bd-init - Initialize beads in the current project
• /bd-workflow - Show the AI-supervised issue workflow guide
• /bd-stats - Show project statistics and progress

Agents

• @task-agent - Autonomous agent that finds and completes ready tasks

MCP Tools Available

The plugin includes a full-featured MCP server with these tools:

• init - Initialize bd in current directory
• create - Create new issue (bug, feature, task, epic, chore)
• list - List issues with filters (status, priority, type, assignee)
• ready - Find tasks with no blockers ready to work on
• show - Show detailed issue info including dependencies
• update - Update issue (status, priority, design, notes, etc)
• close - Close completed issue
• dep - Add dependency (blocks, related, parent-child, discovered-from)
• blocked - Get blocked issues
• stats - Get project statistics

MCP Resources

• beads://quickstart - Interactive quickstart guide

Workflow

The beads workflow is designed for AI agents but works great for humans too:

1. Find ready work: /bd-ready
2. Claim your task: /bd-update <id> in_progress
3. Work on it: Implement, test, document
4. Discover new work: Create issues for bugs/TODOs found during work
5. Complete: /bd-close <id> "Done: <summary>"
6. Repeat: Check for newly unblocked tasks

Issue Types

• bug - Something broken that needs fixing
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature composed of multiple issues
• chore - Maintenance work (dependencies, tooling)

Priority Levels

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (nice-to-have features, minor bugs)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Dependency Types

• blocks - Hard dependency (issue X blocks issue Y from starting)
• related - Soft relationship (issues are connected)
• parent-child - Epic/subtask relationship
• discovered-from - Track issues discovered during work

Only blocks dependencies affect the ready work queue.

Configuration

The MCP server supports these environment variables:

• BEADS_PATH - Path to bd executable (default: bd in PATH)
• BEADS_DB - Path to beads database file (default: auto-discover from cwd)
• BEADS_ACTOR - Actor name for audit trail (default: $USER)
• BEADS_NO_AUTO_FLUSH - Disable automatic JSONL sync (default: false)
• BEADS_NO_AUTO_IMPORT - Disable automatic JSONL import (default: false)

To customize, edit your Claude Code MCP settings or the plugin configuration.

Examples

Basic Task Management

# Create a high-priority bug
/bd-create "Fix authentication" bug 1

# See ready work
/bd-ready

# Start working on bd-10
/bd-update bd-10 in_progress

# Complete the task
/bd-close bd-10 "Fixed auth token validation"

Discovering Work During Development

# Working on bd-10, found a related bug
/bd-create "Add rate limiting to API" feature 2

# Link it to current work (via MCP tool)
# Use `dep` tool: issue="bd-11", depends_on="bd-10", type="discovered-from"

# Close original task
/bd-close bd-10 "Done, discovered bd-11 for rate limiting"

Using the Task Agent

# Let the agent find and complete ready work
@task-agent

# The agent will:
# 1. Find ready work with `ready` tool
# 2. Claim a task by updating status
# 3. Execute the work
# 4. Create issues for discoveries
# 5. Close when complete
# 6. Repeat

Auto-Sync with Git

Beads automatically syncs issues to .beads/issues.jsonl:

• Export: After any CRUD operation (5-second debounce)
• Import: When JSONL is newer than DB (e.g., after git pull)

This enables seamless collaboration:

# Make changes
bd create "Add feature" -p 1

# Changes auto-export after 5 seconds
# Commit when ready
git add .beads/issues.jsonl
git commit -m "Add feature tracking"

# After pull, JSONL auto-imports
git pull
bd ready  # Fresh data from git!

Troubleshooting

Plugin not appearing

1. Check installation: /plugin list
2. Restart Claude Code
3. Verify bd is in PATH: which bd
4. Check uv is installed: which uv

MCP server not connecting

1. Check MCP server list: /mcp
2. Look for "beads" server with plugin indicator
3. Restart Claude Code to reload MCP servers
4. Check logs for errors

Commands not working

1. Make sure you're in a project with beads initialized: /bd-init
2. Check if database exists: ls -la .beads/
3. Try direct MCP tool access instead of slash commands
4. Check the beads CLI works: bd --help

MCP tool errors

1. Verify bd executable location: BEADS_PATH env var
2. Check bd works in terminal: bd stats
3. Review MCP server logs in Claude Code
4. Try reinitializing: /bd-init

Learn More

• GitHub: https://github.com/steveyegge/beads
• Documentation: See README.md in the repository
• Examples: Check examples/ directory for integration patterns
• MCP Server: See integrations/beads-mcp/ for server details

Contributing

Found a bug or have a feature idea? Create an issue in the beads repository!

License

MIT License - see LICENSE file in the repository.