Doctacon

MCP Git Worktree Workflows

Community Doctacon
Updated

MCP server for automated parallel development using git worktrees. Workflows: 1. Voting 2. Orchestration 3. Ad Hoc

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

  1. Install dependencies:
uv add fastmcp  # or pip install fastmcp
  1. 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"]
    }
  }
}
  1. 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 Server ยท Populars

MCP Server ยท New