Skip to main content
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with slash commands, a bundled skill, and lifecycle hooks.

​
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
  • Sync issues via Dolt remotes for distributed workflows

​
Installation

​
Prerequisites

  1. Install beads CLI:
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

​
Install Plugin

There are two ways to install the beads plugin: 
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads

​
Option 2: Local Development

# 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.

​
Restart Claude Code

After installation, restart Claude Code to load the plugin’s commands and hooks.

​
Quick Start

# 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

​
Available Commands

​
Version Management

  • /beads:version - Check bd CLI and plugin versions

​
Core Workflow Commands

  • /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

​
Project Management

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

​
Agents

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

​
MCP Tools

The plugin does not bundle an MCP server — it works through the bd CLI, which Claude Code drives directly (lower token overhead than MCP tool schemas). If you want MCP tools as well — for example in MCP-only surfaces — configure the standalone beads-mcp server alongside the plugin; see MCP Server for its install options and full tool catalog.

​
Workflow

The beads workflow is designed for AI agents but works great for humans too:
  1. Find ready work: /beads:ready
  2. Claim your task: /beads: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: /beads: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

​
Auto-Approval Configuration

These settings apply if you configure the standalone beads-mcp server alongside the plugin. By default, Claude Code asks for confirmation every time an 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.

​
2. Auto-Approve Project MCP Servers

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.

​
3. Manual Approval (Default)

No configuration needed. Claude Code will prompt for approval on each MCP tool invocation. Security Trade-offs:
  • Manual approval (default): Maximum safety, but interrupts workflow frequently
  • Server-level auto-approval: Convenient for trusted projects, but allows any beads operation without confirmation
  • Project-level auto-approval: Good balance for multi-project workflows with project-specific trust levels
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.

​
Examples

​
Basic Task Management

# 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"

​
Discovering Work During Development

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

# Link it to current work
bd dep add bd-11 bd-10 --type discovered-from

# Close original task
/beads: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 Dolt

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)

​
Updating

The beads plugin has three components that may need updating:

​
1. Plugin Updates

Check for plugin updates: 
/plugin update beads
Claude Code will pull the latest version from GitHub. After updating, restart Claude Code to apply plugin changes.

​
2. bd CLI Updates

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 (server-mode only)
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest

# Or with Go (embedded-capable)
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest

​
3. Version Compatibility

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:
  • bd CLI version
  • Plugin version
  • MCP server status
  • Compatibility warnings if versions mismatch
Recommended update workflow:
  1. Check versions: /beads:version
  2. Update bd CLI if needed (see above)
  3. Update plugin: /plugin update beads
  4. Restart Claude Code
  5. Verify: /beads:version

​
Version Numbering

Beads follows semantic versioning. The plugin version tracks the bd CLI version; major version bumps may introduce breaking changes — check CHANGELOG.md for release notes.

​
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: /beads: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: /beads:init

​
Learn More

  • GitHub: https://github.com/gastownhall/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.