docs/PLUGIN.md
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple slash commands and MCP tools.
Beads (bd) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers:
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
There are two ways to install the beads plugin:
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
# Clone the repository (shell command)
git clone https://github.com/gastownhall/beads
cd beads
Then in Claude Code:
# Add local marketplace (Claude Code command)
/plugin marketplace add ./beads
# Install plugin
/plugin install beads
Note: If you want to install the plugin from a different repo, first cd to that repo's directory in your terminal, then use ./beads (or the relative path to the beads directory) in Claude Code.
After installation, restart Claude Code to activate the MCP server.
# Initialize beads in your project
/beads:init
# Create your first issue
/beads:create "Set up project structure" feature 1
# See what's ready to work on
/beads:ready
# Show full workflow guide
/beads:workflow
/beads:version - Check bd CLI, plugin, and MCP server versions/beads:ready - Find tasks with no blockers, ready to work on/beads:create [title] [type] [priority] - Create a new issue interactively/beads:show [issue-id] - Show detailed information about an issue/beads:update [issue-id] [status] - Update issue status or other fields/beads:close [issue-id] [reason] - Close a completed issue/beads:init - Initialize beads in the current project/beads:workflow - Show the AI-supervised issue workflow guide/beads:stats - Show project statistics and progress@task-agent - Autonomous agent that finds and completes ready tasksThe plugin includes a full-featured MCP server with these tools:
init - Initialize bd in current directorycreate - 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 onshow - Show detailed issue info including dependenciesupdate - Update issue (status, priority, design, notes, etc)close - Close completed issuedep - Add dependency (blocks, related, parent-child, discovered-from)blocked - Get blocked issuesstats - Get project statisticsbeads://quickstart - Interactive quickstart guideThe beads workflow is designed for AI agents but works great for humans too:
/beads:ready/beads:update <id> in_progress/beads:close <id> "Done: <summary>"bug - Something broken that needs fixingfeature - New functionalitytask - Work item (tests, docs, refactoring)epic - Large feature composed of multiple issueschore - Maintenance work (dependencies, tooling)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)blocks - Hard dependency (issue X blocks issue Y from starting)related - Soft relationship (issues are connected)parent-child - Epic/subtask relationshipdiscovered-from - Track issues discovered during workOnly blocks dependencies affect the ready work queue.
By default, Claude Code asks for confirmation every time the beads MCP server wants to run a command. This is a security feature, but it can disrupt workflow during active development.
Available Options:
Add to your Claude Code settings.json:
{
"enabledMcpjsonServers": ["beads"]
}
This auto-approves all beads commands without prompting.
Add to your Claude Code settings.json:
{
"enableAllProjectMcpServers": true
}
This auto-approves all MCP servers defined in your project's .mcp.json file. Useful when working across multiple projects with different MCP requirements.
No configuration needed. Claude Code will prompt for approval on each MCP tool invocation.
Security Trade-offs:
Limitation: Claude Code doesn't currently support per-tool approval granularity. You cannot auto-approve only read operations (like bd ready, bd show) while requiring confirmation for mutations (like bd create, bd update). It's all-or-nothing at the server level.
Recommended Configuration:
For active development on trusted projects where you're frequently using beads:
{
"enabledMcpjsonServers": ["beads"]
}
For more information, see the Claude Code settings documentation.
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 sync (default: false)BEADS_NO_AUTO_IMPORT - Disable automatic import (default: false)To customize, edit your Claude Code MCP settings or the plugin configuration.
# Create a high-priority bug
/beads:create "Fix authentication" bug 1
# See ready work
/beads:ready
# Start working on bd-10
/beads:update bd-10 in_progress
# Complete the task
/beads:close bd-10 "Fixed auth token validation"
# Working on bd-10, found a related bug
/beads: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
/beads:close bd-10 "Done, discovered bd-11 for rate limiting"
# 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
Beads automatically commits changes to Dolt history after every write operation. This enables seamless collaboration:
# Make changes
bd create "Add feature" -p 1
# Changes are automatically committed to Dolt history
# Sync with remotes when ready:
bd dolt push
# Pull changes from collaborators:
bd dolt pull
bd ready # Shows issues ready to work on (with fresh data)
The beads plugin has three components that may need updating:
Check for plugin updates:
/plugin update beads
Claude Code will pull the latest version from GitHub. After updating, restart Claude Code to apply MCP server changes.
The plugin requires the bd CLI to be installed. Update it separately:
# Quick update
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
# Or with go
go install github.com/steveyegge/beads/cmd/bd@latest
The MCP server automatically checks bd CLI version on startup and will fail with a clear error if your version is too old.
Check version compatibility manually:
/beads:version
This will show:
Recommended update workflow:
/beads:version/plugin update beads/beads:versionBeads follows semantic versioning. The plugin version tracks the bd CLI version:
/plugin listbd is in PATH: which bdwhich uv/mcp/beads:initls -la .beads/bd --helpbd executable location: BEADS_PATH env varbd works in terminal: bd stats/beads:initexamples/ directory for integration patternsintegrations/beads-mcp/ for server detailsFound a bug or have a feature idea? Create an issue in the beads repository!
MIT License - see LICENSE file in the repository.