---

name: beads-expert description: Expert guidance for Beads (bd) - a Git-backed issue tracker for AI-supervised coding workflows. Use when working with bd CLI commands, MCP tools, hooks, issue tracking, dependencies, workflows, or troubleshooting beads. Covers CLI reference, MCP server integration, Claude Code hooks, event-driven automation, and multi-session context management. allowed-tools: Read, Grep, Glob, WebFetch, WebSearch, Write, Edit, Bash, mcp__beads__*

Beads Expert

Purpose

Provide expert guidance for Beads (bd) - a distributed, Git-backed graph issue tracker designed specifically for AI agents. Beads provides persistent, structured memory for coding agents, replacing messy markdown plans with a dependency-aware graph.

Expertise

• bd CLI commands and workflows
• MCP server tools and integration
• Claude Code hooks and event-driven automation
• Issue lifecycle management (create, update, close, reopen)
• Dependency tracking (blocks, related, parent-child, discovered-from)
• Git synchronization and JSONL storage
• Multi-session context management
• Compaction and memory decay
• Troubleshooting and diagnostics

When to Invoke

Invoke this skill when the user:

• Uses bd CLI commands or asks about beads
• Works with issue tracking in AI workflows
• Configures MCP server or hooks
• Manages dependencies between issues
• Needs to sync issues with git
• Asks about bd ready, bd create, bd update, bd close
• Troubleshoots beads integration
• Wants event-driven automation with hooks

Installation

Copy# Install bd CLI
npm install -g @beads/bd
# OR
brew install steveyegge/beads/bd
# OR
go install github.com/steveyegge/beads/cmd/bd@latest

# Install MCP server (for Claude Code)
pip install beads-mcp
# OR use uv
uv pip install beads-mcp

# Initialize in a project
bd init

Core Concepts

Architecture

CopyBeads Architecture:
┌─────────────────────────────────────────────────────────┐
│                    Claude Code                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ bd CLI       │  │ MCP Server   │  │ Hooks        │  │
│  │ (direct)     │  │ (tools)      │  │ (events)     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
└─────────┼─────────────────┼─────────────────┼──────────┘
          │                 │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────┐
│                  bd Daemon (optional)                   │
│                  Auto-sync, background ops              │
└─────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────┐
│  .beads/                                                │
│  ├── beads.db      (SQLite - local cache, not committed)│
│  └── issues.jsonl  (Git-tracked source of truth)        │
└─────────────────────────────────────────────────────────┘

Issue Types

Issue Statuses

Priorities

Dependency Types

Only blocks dependencies affect the bd ready queue.

CLI Reference

Finding Work

Copy# Find ready work (no blockers)
bd ready --json

# Find stale issues
bd stale --days 30 --json

# List with filters
bd list --status open --priority 1 --json
bd list --assignee alice --type bug --json
bd list --label bug,critical --json      # AND: must have ALL
bd list --label-any frontend,backend --json  # OR: has ANY

Creating Issues

Copy# Basic creation
bd create "Issue title" -t bug|feature|task -p 0-4 --json

# With description
bd create "Fix auth bug" -t bug -p 1 -d "Description here" --json

# With labels
bd create "Issue title" -t bug -p 1 -l bug,critical --json

# Create and link discovered work (single command - preferred)
bd create "Found bug" -t bug -p 1 --deps discovered-from:bd-123 --json

# Create epic with hierarchical children
bd create "Auth System" -t epic -p 1 --json                     # Returns: bd-a3f8e9
bd create "Login UI" -p 1 --parent bd-a3f8e9 --json             # Auto: bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 --json   # Auto: bd-a3f8e9.2

# Read description from file (avoids shell escaping)
bd create "Issue title" --body-file=description.md --json
echo "Description" | bd create "Title" --body-file=- --json

Updating Issues

Copy# Update status
bd update bd-42 --status in_progress --json

# Update priority
bd update bd-42 --priority 1 --json

# Update multiple issues
bd update bd-41 bd-42 bd-43 --priority 0 --json

# Update assignee
bd update bd-42 --assignee alice --json

Completing Work

Copy# Close single issue
bd close bd-42 --reason "Completed" --json

# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json

# Reopen issues
bd reopen bd-42 --reason "Needs more work" --json

Dependencies

Copy# Add blocking dependency (bd-101 depends on bd-100)
bd dep add bd-101 bd-100 --type blocks

# Add discovered-from link
bd dep add bd-101 bd-100 --type discovered-from

# View dependency tree
bd dep tree bd-42

# Show blocked issues
bd blocked --json

Labels

Copy# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json

# Remove label
bd label remove bd-42 urgent --json

# List labels on issue
bd label list bd-42 --json

# List all labels in project
bd label list-all --json

Sync Operations

Copy# Manual sync (export + commit + push)
bd sync

# Check sync status
bd sync --status

# Import from JSONL
bd import -i .beads/issues.jsonl

# Force import (when DB appears synced but isn't)
bd import -i .beads/issues.jsonl --force

Information Commands

Copy# Show issue details
bd show bd-42 --json

# Show multiple issues
bd show bd-41 bd-42 bd-43 --json

# Project statistics
bd stats --json

# Database info
bd info --json

Global Flags

Copy# JSON output (always use for programmatic access)
bd --json <command>

# Sandbox mode (disables daemon, auto-sync)
bd --sandbox <command>

# Skip staleness check
bd --allow-stale <command>

# Custom actor for audit trail
bd --actor alice <command>

MCP Server Integration

Available MCP Tools

The beads MCP server provides these tools:

MCP Context Management

Copy# IMPORTANT: Set workspace before write operations
mcp__beads__context(workspace_root='/path/to/project')

# Then use other tools
mcp__beads__ready()
mcp__beads__create(title="New task", issue_type="task", priority=2)

Context Optimization

The MCP server uses lazy tool schema loading:

1. Use discover_tools() to see available tools (names only)
2. Use get_tool_info(tool_name) for specific tool details
3. This reduces context from ~10-50k tokens to ~2-5k tokens

MCP Resources

Copybeads://quickstart  - Interactive quickstart guide

Hooks and Event-Driven Automation

Claude Code Hooks

Beads integrates with Claude Code through hooks:

Copy{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bd prime"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bd prime"
          }
        ]
      }
    ]
  }
}

Hook Events

Installing Hooks

Copy# Install globally
bd setup claude

# Install for project only
bd setup claude --project

# Use stealth mode (flush only, no git)
bd setup claude --stealth

# Check installation
bd setup claude --check

# Remove hooks
bd setup claude --remove

bd prime Command

The bd prime command outputs workflow context (~1-2k tokens):

• Current project status
• Ready work summary
• Workflow instructions
• Essential commands

This is more context-efficient than MCP tool schemas (10-50k tokens).

Workflow Patterns

Standard Agent Workflow

Copy# 1. Start of session - find work
bd ready --json

# 2. Claim task
bd update bd-42 --status in_progress --json

# 3. Work on it...

# 4. Discover related work (create and link in one command)
bd create "Found bug during work" -t bug -p 1 --deps discovered-from:bd-42 --json

# 5. Complete original task
bd close bd-42 --reason "Implemented and tested" --json

# 6. End of session - ALWAYS sync
bd sync

Session Close Protocol

CRITICAL: Before ending any session:

Copy# 1. Check what changed
git status

# 2. Stage code changes
git add <files>

# 3. Sync beads changes
bd sync

# 4. Commit code
git commit -m "..."

# 5. Sync any new beads changes
bd sync

# 6. Push to remote
git push

Work is NOT complete until git push succeeds.

Batch Operations

Copy# Update multiple issues at once
bd update bd-41 bd-42 bd-43 --priority 0 --json

# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json

# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json

Hierarchical Issue Creation

Copy# Create epic
bd create "Auth System Overhaul" -t epic -p 1 --json
# Returns: bd-a3f8

# Create subtasks (auto-numbered)
bd create "Implement OAuth" -p 1 --parent bd-a3f8 --json   # bd-a3f8.1
bd create "Add MFA support" -p 1 --parent bd-a3f8 --json   # bd-a3f8.2
bd create "Write tests" -p 1 --parent bd-a3f8 --json       # bd-a3f8.3

# Subtasks can have subtasks (up to 3 levels)
bd create "Unit tests" -p 2 --parent bd-a3f8.3 --json      # bd-a3f8.3.1

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)

Copy# 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  # Shows fresh data from git

Important Git Rules

• Always commit .beads/issues.jsonl with code changes
• Never commit .beads/beads.db (SQLite cache)
• Run bd sync at end of sessions

Troubleshooting

Common Issues

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. Restart Claude Code
3. Check logs for errors

Staleness errors:

Copy# Force import
bd import -i .beads/issues.jsonl --force

# Or skip staleness check (emergency)
bd --allow-stale ready --json

Sandboxed environments:

Copy# Enable sandbox mode
bd --sandbox <command>

# Equivalent to:
bd --no-daemon --no-auto-flush --no-auto-import <command>

Missing parent errors during import:

Copy# Allow orphans (default)
bd import -i issues.jsonl --orphan-handling allow

# Resurrect deleted parents
bd import -i issues.jsonl --orphan-handling resurrect

# Strict mode (fail on missing parent)
bd import -i issues.jsonl --orphan-handling strict

Diagnostics

Copy# Check database and daemon status
bd info --json

# Run health checks
bd admin validate --json

# Check daemon health
bd daemons health --json

# View daemon logs
bd daemons logs /path/to/workspace -n 100

Configuration

Environment Variables

MCP Compaction Settings

Best Practices

For AI Agents

1. Always use --json flag for programmatic access
2. Use bd ready first to find available work
3. Link discovered work with --deps discovered-from:<parent>
4. Run bd sync at end of sessions to push changes
5. Never create markdown TODO lists - use bd instead

For Multi-Session Work

1. Check bd ready at session start
2. Update status to in_progress when claiming work
3. Create issues for discovered work instead of notes
4. Close issues with reasons for audit trail
5. Always sync and push before ending session

Context Efficiency

1. Prefer CLI + Hooks over MCP when shell is available
2. Use bd prime for context injection (~1-2k tokens)
3. Use MCP discover_tools() instead of loading all schemas
4. Set workspace context once then reuse

Resources

• Repository: https://github.com/steveyegge/beads
• Documentation: See docs/ in repository
• CLI Reference: docs/CLI_REFERENCE.md
• MCP Server: integrations/beads-mcp/
• Plugin: .claude-plugin/