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

Related MCP server: GitHub MCP Server

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

🛠️ Available Tools

Core Voting Workflow

create_voting_worktrees: Creates worktrees and starts automated execution
list_sessions: Monitor all active sessions and their progress
evaluate_implementations: Get detailed ranking and evaluation of all variants
auto_select_best: Automatically choose and finalize the best implementation
finalize_best: Manually select a specific implementation
cleanup_session: Force cleanup of sessions

Additional Workflows

create_adhoc_worktree: Single worktree for quick tasks
create_orchestrated_worktrees: Multiple worktrees for coordinated subtasks

Utility Functions

get_worktree_info: Inspect specific worktree details
mark_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

⚡ Performance Notes

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

MCP Worktree Voting Server