johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Git worktree compatibility (PR #478)

Browse Source 
Adds comprehensive Git worktree support for beads issue tracking:

Core changes:
- New internal/git/gitdir.go package for worktree detection
- GetGitDir() returns proper .git location (main repo, not worktree)
- Updated all hooks to use git.GetGitDir() instead of local helper
- BeadsDir() now prioritizes main repository's .beads directory

Features:
- Hooks auto-install in main repo when run from worktree
- Shared .beads directory across all worktrees
- Config option no-install-hooks to disable auto-install
- New bd worktree subcommand for diagnostics

Documentation:
- New docs/WORKTREES.md with setup instructions
- Updated CHANGELOG.md and AGENT_INSTRUCTIONS.md

Testing:
- Updated tests to use exported git.GetGitDir()
- Added worktree detection tests

Co-authored-by: Claude <noreply@anthropic.com>
Closes: #478
This commit is contained in:
matt wilkie
2025-12-13 10:40:40 -08:00
committed by Steve Yegge
parent de7b511765
commit e01b7412d9
64 changed files with 1895 additions and 3708 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/PLUGIN.md
View File

@@ -40,22 +40,17 @@ There are two ways to install the beads plugin:
#### Option 2: Local Development
```bash
# Clone the repository (shell command)
# Clone the repository
git clone https://github.com/steveyegge/beads
cd beads
```
Then in Claude Code:
```
# Add local marketplace (Claude Code command - note: use ./beads not .)
/plugin marketplace add ./beads
# Add local marketplace
/plugin marketplace add .
# 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.
@@ -64,37 +59,37 @@ After installation, restart Claude Code to activate the MCP server.
```bash
# Initialize beads in your project
/beads:init
/bd-init
# Create your first issue
/beads:create "Set up project structure" feature 1
/bd-create "Set up project structure" feature 1
# See what's ready to work on
/beads:ready
/bd-ready
# Show full workflow guide
/beads:workflow
/bd-workflow
```
## Available Commands
### Version Management
- **`/beads:version`** - Check bd CLI, plugin, and MCP server versions
- **`/bd-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
- **`/bd-ready`** - Find tasks with no blockers, ready to work on
- **`/bd-create [title] [type] [priority]`** - Create a new issue interactively
- **`/bd-show [issue-id]`** - Show detailed information about an issue
- **`/bd-update [issue-id] [status]`** - Update issue status or other fields
- **`/bd-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
- **`/bd-init`** - Initialize beads in the current project
- **`/bd-workflow`** - Show the AI-supervised issue workflow guide
- **`/bd-stats`** - Show project statistics and progress
### Agents
@@ -123,11 +118,11 @@ The plugin includes a full-featured MCP server with these tools:
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`
1. **Find ready work**: `/bd-ready`
2. **Claim your task**: `/bd-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>"`
5. **Complete**: `/bd-close <id> "Done: <summary>"`
6. **Repeat**: Check for newly unblocked tasks
## Issue Types
@@ -229,29 +224,29 @@ To customize, edit your Claude Code MCP settings or the plugin configuration.
```bash
# Create a high-priority bug
/beads:create "Fix authentication" bug 1
/bd-create "Fix authentication" bug 1
# See ready work
/beads:ready
/bd-ready
# Start working on bd-10
/beads:update bd-10 in_progress
/bd-update bd-10 in_progress
# Complete the task
/beads:close bd-10 "Fixed auth token validation"
/bd-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
/bd-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"
/bd-close bd-10 "Done, discovered bd-11 for rate limiting"
```
### Using the Task Agent
@@ -321,7 +316,7 @@ The MCP server **automatically checks** bd CLI version on startup and will fail
Check version compatibility manually:
```bash
/beads:version
/bd-version
```
This will show:
@@ -331,11 +326,11 @@ This will show:
- Compatibility warnings if versions mismatch
**Recommended update workflow:**
1. Check versions: `/beads:version`
1. Check versions: `/bd-version`
2. Update bd CLI if needed (see above)
3. Update plugin: `/plugin update beads`
4. Restart Claude Code
5. Verify: `/beads:version`
5. Verify: `/bd-version`
### Version Numbering
@@ -362,7 +357,7 @@ Beads follows semantic versioning. The plugin version tracks the bd CLI version:
### Commands not working
1. Make sure you're in a project with beads initialized: `/beads:init`
1. Make sure you're in a project with beads initialized: `/bd-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`
@@ -372,7 +367,7 @@ Beads follows semantic versioning. The plugin version tracks the bd CLI version:
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`
4. Try reinitializing: `/bd-init`
## Learn More