MCP Git Worktree Workflows
An MCP (Model Context Protocol) server that implements automated parallel development using git worktrees.
🚀 Key Features
- Voting Workflow: Intelligently ranks and selects the highest-quality implementation
- Ad Hoc Workflow: Quick single-worktree creation for simple tasks
- Orchestration Workflow: Break complex tasks into subtasks with coordinated execution
- Clean Workflow: Automatic cleanup of unsuccessful variants
Installation
- Install dependencies:
uv add fastmcp # or pip install fastmcp
- Add the server to Claude Code:
Option A: Using Claude Code CLI (Recommended)
# For project-specific use
claude mcp add worktree-workflows python /path/to/mcp-servers/worktree_workflows.py
# For global use across all projects
claude mcp add --scope user worktree-workflows python /path/to/mcp-servers/worktree_workflows.py
Option B: Manual Configuration
Add to your MCP configuration file:
{
"mcpServers": {
"worktree-workflows": {
"command": "python",
"args": ["/path/to/mcp-servers/worktree_workflows.py"]
}
}
}
- Restart Claude Code or use
/mcp command to reconnect
🔄 Workflow Options
1. Voting Pattern (Multiple Implementations)
create_voting_worktrees(
task="Rewrite the README.md with better examples",
num_variants=5,
target_repo="lombardi" # Optional: specify repository
)
2. Ad Hoc Single Worktree
create_adhoc_worktree(
task="Fix the login bug in auth.js",
target_repo="my-app" # Optional
)
3. Orchestrated Subtasks
create_orchestrated_worktrees(
task="Implement user authentication system",
subtasks=[
"Create database models for users and sessions",
"Build authentication API endpoints",
"Implement JWT token generation and validation",
"Create login/logout UI components",
"Add authentication middleware and route protection"
],
target_repo="my-app" # Optional
)
📊 Evaluation Metrics
The system automatically evaluates implementations using:
- Code Changes (30 points): Has meaningful modifications
- Test Success (50 points): Tests pass successfully
- File Impact (up to 20 points): Number of files modified
- Quality Heuristics: Additional scoring based on implementation patterns
Core Voting Workflow
create_voting_worktrees: Creates worktrees and starts automated executionlist_sessions: Monitor all active sessions and their progressevaluate_implementations: Get detailed ranking and evaluation of all variantsauto_select_best: Automatically choose and finalize the best implementationfinalize_best: Manually select a specific implementationcleanup_session: Force cleanup of sessions
Additional Workflows
create_adhoc_worktree: Single worktree for quick taskscreate_orchestrated_worktrees: Multiple worktrees for coordinated subtasks
Utility Functions
get_worktree_info: Inspect specific worktree detailsmark_implementation_complete: Manually mark implementations as done
💡 Example Use Cases
Voting Pattern
Perfect for:
- Architecture Exploration: Try different design patterns simultaneously
- Library Comparison: Implement with various frameworks/libraries
- Algorithm Optimization: Test multiple approaches to performance problems
- UI/UX Variants: Create different interface implementations
Ad Hoc Tasks
Great for:
- Bug Fixes: Quick isolation and resolution
- Small Features: Rapid implementation without overhead
- Experiments: Try ideas without affecting main branch
Orchestrated Development
Ideal for:
- Large Features: Break down and parallelize development
- System Refactoring: Coordinate multiple related changes
- API Development: Build endpoints, models, and tests in parallel
🎯 Quick Start Examples
Example 1: Voting Pattern
# 1. Start automated voting session
create_voting_worktrees(
task="Add Redis caching to the user service with error handling",
num_variants=3
)
# 2. Check progress (Claude is working automatically)
list_sessions()
# Returns: "2/3 complete, 3/3 executed"
# 3. View results and rankings
evaluate_implementations(session_id="xyz789")
# Shows ranked implementations with scores
# 4. Auto-select winner and merge
auto_select_best(session_id="xyz789", merge_to_main=true)
# Merges best implementation, cleans up others
Example 2: Quick Fix
# Create single worktree for a bug fix
create_adhoc_worktree(
task="Fix null pointer exception in user profile component"
)
# Claude starts immediately in new Terminal window
Example 3: Feature Development
# Break down complex feature into subtasks
create_orchestrated_worktrees(
task="Add real-time notifications",
subtasks=[
"Set up WebSocket server infrastructure",
"Create notification database schema and models",
"Build notification API endpoints",
"Implement frontend notification component",
"Add notification preferences to user settings"
]
)
# 5 Terminal windows open, each with Claude working on a subtask
- Concurrent Execution: All Claude instances run in parallel
- Automatic Cleanup: Failed/low-quality implementations are removed
- Resource Efficient: Only keeps the winning implementation
- Fast Evaluation: Uses git diff stats and automated test detection
- Smart Naming: Worktrees include task description for easy identification
🔧 Advanced Features
Worktree Naming
- Branches and directories now include task descriptions
- Format:
{session-id}-{task-slug}-{variant} - Example:
abc123-fix-login-bug-var1
Origin/Main Support
- Ad hoc worktrees always branch from
origin/main - Ensures clean starting point for isolated tasks
- Automatically fetches latest changes
Terminal Integration
- Automatically spawns Terminal windows (macOS)
- Each worktree gets its own Claude session
- No manual terminal management required