9f3837558b
Adds a Claude Code plugin for one-command installation of beads via /plugin command. The plugin bundles the MCP server, slash commands, and an autonomous task agent. Components: - Plugin metadata with MCP server configuration - 8 slash commands for core workflow (/bd-ready, /bd-create, etc.) - Task agent for autonomous execution (@task-agent) - Comprehensive plugin documentation (PLUGIN.md) The plugin provides a lower-friction installation path for Claude Code users who want integrated slash commands rather than direct MCP tools. Related: https://github.com/steveyegge/beads/issues/28 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
272 lines
7.2 KiB
Markdown
272 lines
7.2 KiB
Markdown
# 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:
|
|
```bash
|
|
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
|
```
|
|
|
|
2. Install Python and uv (for MCP server):
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# In Claude Code
|
|
/plugin marketplace add steveyegge/beads
|
|
/plugin install beads
|
|
```
|
|
|
|
#### Option 2: Local Development
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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.
|