gastownhall__beads/docs/integrations/claude-code-plugin.md

---
title: Beads Claude Code Plugin
description: Install the beads Claude Code plugin for /beads slash commands, a bundled skill, and session lifecycle hooks
---

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:
```bash
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```


### Install Plugin

There are two ways to install the beads plugin:

#### Option 1: From GitHub (Recommended)

```bash
# In Claude Code
/plugin marketplace add gastownhall/beads
/plugin install beads
```

#### Option 2: Local Development

```bash
# 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

```bash
# 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](/integrations/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](/integrations/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:**

#### 1. Auto-Approve All Beads Tools (Recommended for Trusted Projects)

Add to your Claude Code `settings.json`:

```json
{
  "enabledMcpjsonServers": ["beads"]
}
```

This auto-approves all beads commands without prompting.

#### 2. Auto-Approve Project MCP Servers

Add to your Claude Code `settings.json`:

```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:

```json
{
  "enabledMcpjsonServers": ["beads"]
}
```

For more information, see the [Claude Code settings documentation](https://docs.claude.com/en/docs/claude-code/settings).


## Examples

### Basic Task Management

```bash
# 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

```bash
# 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

```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 Dolt

Beads automatically commits changes to Dolt history after every write operation. This enables seamless collaboration:

```bash
# 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:
```bash
/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:

```bash
# 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:
```bash
/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.