beads/docs/PLUGIN.md
matt wilkie 0c47b3c5ac
fix(init): use git origin as default Dolt remote (#3909)
* fix(init): wire git origin as Dolt remote

Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.

Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.

_codex-gpt-5-xhigh on behalf of maphew_

* test: keep embedded command stderr out of parsed stdout

Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_

---------

Co-authored-by: CI Bot <ci@beads.test>
2026-05-13 07:02:39 -07:00

390 lines
11 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
- 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
```
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 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 activate the MCP server.
## 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, plugin, and MCP server 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 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**: `/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
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:**
#### 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).
### Environment Variables
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.
## 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 (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"
```
### 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 MCP server 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:
- Plugin 0.9.2 requires bd CLI >= 0.9.0 (checked automatically at startup)
- 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.