claude-evolve 1.2.13 → 1.3.0

package/bin/claude-evolve-run

@@ -21,6 +21,14 @@ while [[ $# -gt 0 ]]; do
     timeout_seconds="$2"
     shift 2
     ;;
+  --parallel)
+    force_parallel="true"
+    shift
+    ;;
+  --sequential)
+    force_sequential="true"
+    shift
+    ;;
   --help)
     cat <<EOF
 claude-evolve run - Execute evolution candidates
@@ -30,6 +38,8 @@ USAGE:
 
 OPTIONS:
   --timeout <sec>  Kill evaluator after specified seconds (default: no timeout)
+  --parallel       Force parallel execution mode
+  --sequential     Force sequential execution mode
   --help           Show this help message
 
 DESCRIPTION:
@@ -49,8 +59,29 @@ EOF
   esac
 done
 
-echo "[INFO] Starting continuous evolution run..."
-echo "[INFO] Will continue running until no more pending candidates or 5 consecutive failures"
+# Determine execution mode
+use_parallel=false
+if [[ "$force_parallel" == "true" ]]; then
+  use_parallel=true
+  echo "[INFO] Using parallel mode (forced via --parallel)"
+elif [[ "$force_sequential" == "true" ]]; then
+  use_parallel=false
+  echo "[INFO] Using sequential mode (forced via --sequential)"
+elif [[ "$PARALLEL_ENABLED" == "true" || "$PARALLEL_ENABLED" == "1" ]]; then
+  use_parallel=true
+  echo "[INFO] Using parallel mode (enabled in config)"
+else
+  echo "[INFO] Using sequential mode (default)"
+fi
+
+if [[ "$use_parallel" == "true" ]]; then
+  echo "[INFO] Starting parallel evolution run with up to $MAX_WORKERS workers"
+  exec "$SCRIPT_DIR/claude-evolve-run-parallel" ${timeout_seconds:+--timeout "$timeout_seconds"}
+else
+  echo "[INFO] Starting continuous evolution run..."
+  echo "[INFO] Will continue running until no more pending candidates or 5 consecutive failures"
+fi
+
 [[ -n $timeout_seconds ]] && echo "[INFO] Using timeout: ${timeout_seconds} seconds per evaluation"
 
 # Prepare logging directory

package/bin/claude-evolve-run-parallel

@@ -0,0 +1,219 @@
+#!/bin/bash
+# Parallel evolution dispatcher - manages worker pool
+
+set -e
+
+# Load configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/config.sh
+source "$SCRIPT_DIR/../lib/config.sh"
+# shellcheck source=../lib/csv-lock.sh
+source "$SCRIPT_DIR/../lib/csv-lock.sh"
+load_config
+
+# Parse arguments
+timeout_seconds=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  --timeout)
+    timeout_seconds="$2"
+    shift 2
+    ;;
+  *)
+    echo "[ERROR] Unknown option: $1" >&2
+    exit 1
+    ;;
+  esac
+done
+
+echo "[DISPATCHER] Starting parallel evolution with $MAX_WORKERS max workers"
+[[ -n $timeout_seconds ]] && echo "[DISPATCHER] Using timeout: ${timeout_seconds} seconds per worker"
+
+# Validate workspace
+if [[ ! -d "$FULL_EVOLUTION_DIR" ]]; then
+  echo "[ERROR] Evolution directory not found: $FULL_EVOLUTION_DIR" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FULL_CSV_PATH" ]]; then
+  echo "[ERROR] CSV file not found: $FULL_CSV_PATH" >&2
+  exit 1
+fi
+
+# Prepare logging
+mkdir -p logs
+
+# Track active workers
+declare -A worker_pids=()
+consecutive_failures=0
+MAX_FAILURES=10
+rate_limit_hit=false
+
+# Count pending candidates
+count_pending() {
+  if ! read_csv_with_lock csv_content; then
+    echo "0"
+    return
+  fi
+  
+  echo "$csv_content" | awk -F',' 'NR>1 && $5 == "pending" { count++ } END { print count+0 }'
+}
+
+# Start a worker
+start_worker() {
+  local worker_cmd="$SCRIPT_DIR/claude-evolve-worker"
+  [[ -n $timeout_seconds ]] && worker_cmd="$worker_cmd --timeout $timeout_seconds"
+  
+  echo "[DISPATCHER] Starting worker..."
+  $worker_cmd &
+  local pid=$!
+  worker_pids[$pid]=1
+  echo "[DISPATCHER] Worker $pid started"
+}
+
+# Check worker exit status and handle accordingly
+handle_worker_exit() {
+  local pid="$1"
+  local exit_code="$2"
+  
+  case $exit_code in
+    0)
+      echo "[DISPATCHER] Worker $pid completed successfully"
+      consecutive_failures=0
+      ;;
+    1)
+      echo "[DISPATCHER] Worker $pid failed"
+      ((consecutive_failures++))
+      ;;
+    2)
+      echo "[DISPATCHER] Worker $pid hit rate limit"
+      rate_limit_hit=true
+      ;;
+    130)
+      echo "[DISPATCHER] Worker $pid interrupted"
+      ;;
+    *)
+      echo "[DISPATCHER] Worker $pid exited with code $exit_code"
+      ((consecutive_failures++))
+      ;;
+  esac
+  
+  # Remove from tracking
+  unset worker_pids[$pid]
+}
+
+# Signal handler for graceful shutdown
+shutdown_workers() {
+  echo "[DISPATCHER] Shutting down workers..."
+  for pid in "${!worker_pids[@]}"; do
+    if kill -0 "$pid" 2>/dev/null; then
+      echo "[DISPATCHER] Stopping worker $pid"
+      kill -TERM "$pid" 2>/dev/null || true
+    fi
+  done
+  
+  # Wait for workers to exit
+  local timeout=10
+  while [[ ${#worker_pids[@]} -gt 0 && $timeout -gt 0 ]]; do
+    sleep 1
+    ((timeout--))
+    
+    for pid in "${!worker_pids[@]}"; do
+      if ! kill -0 "$pid" 2>/dev/null; then
+        unset worker_pids[$pid]
+      fi
+    done
+  done
+  
+  # Force kill remaining workers
+  for pid in "${!worker_pids[@]}"; do
+    if kill -0 "$pid" 2>/dev/null; then
+      echo "[DISPATCHER] Force killing worker $pid"
+      kill -KILL "$pid" 2>/dev/null || true
+    fi
+  done
+  
+  echo "[DISPATCHER] Shutdown complete"
+  exit 0
+}
+
+trap shutdown_workers INT TERM
+
+# Main dispatcher loop
+echo "[DISPATCHER] Starting main dispatch loop"
+
+while true; do
+  # Check if too many consecutive failures
+  if [[ $consecutive_failures -ge $MAX_FAILURES ]]; then
+    echo "[ERROR] Too many consecutive failures ($consecutive_failures). Stopping." >&2
+    break
+  fi
+  
+  # Check if rate limit was hit
+  if [[ $rate_limit_hit == true ]]; then
+    echo "[DISPATCHER] Rate limit detected. Waiting 60 seconds before retrying..."
+    sleep 60
+    rate_limit_hit=false
+  fi
+  
+  # Count pending work
+  pending_count=$(count_pending)
+  active_workers=${#worker_pids[@]}
+  
+  echo "[DISPATCHER] Status: $pending_count pending, $active_workers active workers"
+  
+  # If no pending work and no active workers, try to generate more ideas
+  if [[ $pending_count -eq 0 && $active_workers -eq 0 ]]; then
+    echo "[DISPATCHER] No work available. Generating new ideas..."
+    
+    ideate_script="$SCRIPT_DIR/claude-evolve-ideate"
+    if [[ ! -f "$ideate_script" ]]; then
+      echo "[DISPATCHER] No ideate script found. Evolution complete."
+      break
+    fi
+    
+    if ! "$ideate_script"; then
+      echo "[ERROR] Failed to generate new ideas" >&2
+      break
+    fi
+    
+    # Recount after ideation
+    pending_count=$(count_pending)
+    echo "[DISPATCHER] Generated ideas. New pending count: $pending_count"
+  fi
+  
+  # Start workers if we have pending work and capacity
+  while [[ $pending_count -gt 0 && $active_workers -lt $MAX_WORKERS ]]; do
+    start_worker
+    active_workers=${#worker_pids[@]}
+    ((pending_count--))  # Optimistically assume this will be picked up
+  done
+  
+  # If no active workers and no pending work, we're done
+  if [[ $active_workers -eq 0 && $pending_count -eq 0 ]]; then
+    echo "[DISPATCHER] No active workers and no pending work. Evolution complete."
+    break
+  fi
+  
+  # Wait for any worker to finish
+  if [[ $active_workers -gt 0 ]]; then
+    # Wait for any child process to exit
+    wait -n
+    
+    # Check which workers have finished
+    for pid in "${!worker_pids[@]}"; do
+      if ! kill -0 "$pid" 2>/dev/null; then
+        # Get exit status
+        wait "$pid"
+        exit_code=$?
+        handle_worker_exit "$pid" "$exit_code"
+      fi
+    done
+  else
+    # No active workers but we might be waiting for ideation or have pending work
+    sleep 1
+  fi
+done
+
+echo "[DISPATCHER] Evolution run complete"

package/bin/claude-evolve-worker

@@ -0,0 +1,259 @@
+#!/bin/bash
+# Worker process for parallel evolution execution
+# Processes a single evolution candidate and exits
+
+set -e
+
+# Load configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/config.sh
+source "$SCRIPT_DIR/../lib/config.sh"
+# shellcheck source=../lib/csv-lock.sh
+source "$SCRIPT_DIR/../lib/csv-lock.sh"
+load_config
+
+# Parse arguments
+timeout_seconds=""
+candidate_id=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  --timeout)
+    if [[ -z ${2:-} ]] || [[ ! $2 =~ ^[0-9]+$ ]] || [[ $2 -eq 0 ]]; then
+      echo "[ERROR] --timeout requires a positive integer (seconds)" >&2
+      exit 1
+    fi
+    timeout_seconds="$2"
+    shift 2
+    ;;
+  --id)
+    candidate_id="$2"
+    shift 2
+    ;;
+  *)
+    echo "[ERROR] Unknown option: $1" >&2
+    exit 1
+    ;;
+  esac
+done
+
+# If no ID provided, find next pending
+if [[ -z $candidate_id ]]; then
+  candidate_id=$(find_next_pending_with_lock)
+  if [[ -z $candidate_id ]]; then
+    echo "[INFO] No pending candidates found"
+    exit 0
+  fi
+else
+  # Mark specified candidate as running
+  update_csv_row_with_lock "$candidate_id" "status" "running"
+fi
+
+echo "[WORKER-$$] Processing candidate ID: $candidate_id"
+
+# Validate workspace
+if [[ ! -d "$FULL_EVOLUTION_DIR" ]]; then
+  echo "[ERROR] Evolution directory not found: $FULL_EVOLUTION_DIR" >&2
+  exit 1
+fi
+
+# Create log file for this run
+mkdir -p logs
+LOGFILE="logs/worker-${candidate_id}-$(date +%Y%m%d_%H%M%S).txt"
+
+# Find candidate in CSV
+row_data=""
+if ! read_csv_with_lock csv_content; then
+  echo "[ERROR] Failed to read CSV" >&2
+  exit 1
+fi
+
+# Extract candidate data
+found=false
+while IFS=, read -r csv_id csv_based_on csv_desc csv_perf csv_stat; do
+  if [[ $csv_id == "$candidate_id" ]]; then
+    id="$csv_id"
+    based_on_id="$csv_based_on"
+    description="$csv_desc"
+    performance="$csv_perf"
+    status="$csv_stat"
+    found=true
+    break
+  fi
+done <<< "$csv_content"
+
+if [[ $found == false ]]; then
+  echo "[ERROR] Candidate ID not found: $candidate_id" >&2
+  exit 1
+fi
+
+# Clean up description
+description=${description#\"}
+description=${description%\"}
+
+echo "[WORKER-$$] Description: $description"
+echo "[WORKER-$$] Based on ID: $based_on_id"
+
+# Determine parent algorithm
+if [[ -z $based_on_id || $based_on_id == "0" || $based_on_id == '""' ]]; then
+  parent_file="$FULL_ALGORITHM_PATH"
+  echo "[WORKER-$$] Using base algorithm"
+else
+  # Handle both old and new format IDs
+  if [[ $based_on_id =~ ^[0-9]+$ ]]; then
+    parent_file="$FULL_OUTPUT_DIR/evolution_id${based_on_id}.py"
+  else
+    parent_file="$FULL_OUTPUT_DIR/evolution_${based_on_id}.py"
+  fi
+  
+  if [[ ! -f $parent_file ]]; then
+    echo "[ERROR] Parent algorithm not found: $parent_file" >&2
+    update_csv_row_with_lock "$candidate_id" "status" "failed"
+    exit 1
+  fi
+fi
+
+# Generate output file
+if [[ $id =~ ^[0-9]+$ ]]; then
+  output_file="$FULL_OUTPUT_DIR/evolution_id${id}.py"
+else
+  output_file="$FULL_OUTPUT_DIR/evolution_${id}.py"
+fi
+
+# Copy parent to output
+cp "$parent_file" "$output_file"
+echo "[WORKER-$$] Copied parent to: $output_file"
+
+# Generate mutation (skip for baseline)
+if [[ $id == "000" || $id == "0" || $id == "gen00-000" ]]; then
+  echo "[WORKER-$$] Baseline algorithm - skipping mutation"
+else
+  # Check for claude CLI
+  claude_cmd="${CLAUDE_CMD:-claude}"
+  if ! command -v "$claude_cmd" >/dev/null 2>&1; then
+    echo "[ERROR] Claude CLI not found" >&2
+    update_csv_row_with_lock "$candidate_id" "status" "failed"
+    exit 1
+  fi
+  
+  CLAUDE_MODEL="sonnet"
+  echo "[WORKER-$$] Using Claude $CLAUDE_MODEL for mutation"
+  
+  # Create mutation prompt
+  prompt="Edit the file $output_file to implement this specific change: $description
+
+Requirements:
+- Edit the file directly (don't just provide comments or suggestions)
+- Maintain the same function signatures and interfaces
+- Make the specific change described above
+- Ensure the code runs without syntax errors
+- Add proper error handling if needed
+
+The file currently contains the parent algorithm. Modify it according to the description above."
+  
+  # Log prompt
+  {
+    echo "=== WORKER $$ - MUTATION PROMPT ==="
+    echo "ID: $id"
+    echo "Timestamp: $(date)"
+    echo "$prompt"
+    echo
+  } >> "$LOGFILE"
+  
+  # Call Claude
+  echo "[WORKER-$$] Calling Claude to apply mutation..."
+  claude_output=$(echo "$prompt" | "$claude_cmd" --dangerously-skip-permissions --model $CLAUDE_MODEL -p 2>&1 | tee -a "$LOGFILE")
+  claude_exit_code=${PIPESTATUS[1]}
+  
+  # Check for rate limit
+  if echo "$claude_output" | grep -q "Claude AI usage limit reached"; then
+    echo "[ERROR] Claude API rate limit reached" >&2
+    # Reset to pending so it can be retried later
+    update_csv_row_with_lock "$candidate_id" "status" "pending"
+    exit 2  # Special exit code for rate limit
+  fi
+  
+  if [[ $claude_exit_code -ne 0 ]]; then
+    echo "[ERROR] Claude failed to mutate algorithm" >&2
+    update_csv_row_with_lock "$candidate_id" "status" "failed"
+    exit 1
+  fi
+fi
+
+# Run evaluator
+echo "[WORKER-$$] Running evaluation..."
+eval_output=""
+eval_exit_code=0
+
+if [[ -n $timeout_seconds ]]; then
+  echo "[WORKER-$$] Evaluation timeout: ${timeout_seconds}s"
+  if eval_output=$(timeout "$timeout_seconds" "$PYTHON_CMD" "$FULL_EVALUATOR_PATH" "$output_file" 2>&1); then
+    eval_exit_code=0
+  else
+    eval_exit_code=$?
+    if [[ $eval_exit_code -eq 124 ]]; then
+      echo "[ERROR] Evaluation timed out" >&2
+      update_csv_row_with_lock "$candidate_id" "status" "timeout"
+      exit 1
+    fi
+  fi
+else
+  if eval_output=$("$PYTHON_CMD" "$FULL_EVALUATOR_PATH" "$output_file" 2>&1); then
+    eval_exit_code=0
+  else
+    eval_exit_code=$?
+  fi
+fi
+
+# Log evaluator output
+{
+  echo "=== WORKER $$ - EVALUATOR OUTPUT ==="
+  echo "Exit code: $eval_exit_code"
+  echo "$eval_output"
+  echo
+} >> "$LOGFILE"
+
+# Process results
+if [[ $eval_exit_code -eq 0 ]]; then
+  # Extract score
+  if score=$(echo "$eval_output" | grep -o '"score"[[:space:]]*:[[:space:]]*[0-9.]*' | cut -d: -f2 | tr -d ' '); then
+    if [[ -n $score ]]; then
+      if (( $(echo "$score == 0" | bc -l) )); then
+        update_csv_row_with_lock "$candidate_id" "status" "failed"
+        update_csv_row_with_lock "$candidate_id" "performance" "$score"
+        echo "[WORKER-$$] ✗ Evaluation failed with score 0"
+        exit 1
+      else
+        update_csv_row_with_lock "$candidate_id" "performance" "$score"
+        update_csv_row_with_lock "$candidate_id" "status" "complete"
+        echo "[WORKER-$$] ✓ Evaluation complete, score: $score"
+        exit 0
+      fi
+    fi
+  fi
+  
+  # Try "performance" field
+  if score=$(echo "$eval_output" | grep -o '"performance"[[:space:]]*:[[:space:]]*[0-9.]*' | cut -d: -f2 | tr -d ' '); then
+    if [[ -n $score ]]; then
+      if (( $(echo "$score == 0" | bc -l) )); then
+        update_csv_row_with_lock "$candidate_id" "status" "failed"
+        update_csv_row_with_lock "$candidate_id" "performance" "$score"
+        echo "[WORKER-$$] ✗ Evaluation failed with score 0"
+        exit 1
+      else
+        update_csv_row_with_lock "$candidate_id" "performance" "$score"
+        update_csv_row_with_lock "$candidate_id" "status" "complete"
+        echo "[WORKER-$$] ✓ Evaluation complete, score: $score"
+        exit 0
+      fi
+    fi
+  fi
+  
+  echo "[ERROR] No score found in evaluator output" >&2
+  update_csv_row_with_lock "$candidate_id" "status" "failed"
+  exit 1
+else
+  echo "[ERROR] Evaluator failed with exit code $eval_exit_code" >&2
+  update_csv_row_with_lock "$candidate_id" "status" "failed"
+  exit 1
+fi

package/lib/config.sh

@@ -19,6 +19,11 @@ DEFAULT_STRUCTURAL_MUTATION=3
 DEFAULT_CROSSOVER_HYBRID=4
 DEFAULT_NUM_ELITES=3
 
+# Default parallel execution values
+DEFAULT_PARALLEL_ENABLED=false
+DEFAULT_MAX_WORKERS=4
+DEFAULT_LOCK_TIMEOUT=30
+
 # Load configuration from config file
 load_config() {
   # Set defaults first
@@ -38,6 +43,11 @@ load_config() {
   STRUCTURAL_MUTATION="$DEFAULT_STRUCTURAL_MUTATION"
   CROSSOVER_HYBRID="$DEFAULT_CROSSOVER_HYBRID"
   NUM_ELITES="$DEFAULT_NUM_ELITES"
+  
+  # Set parallel execution defaults
+  PARALLEL_ENABLED="$DEFAULT_PARALLEL_ENABLED"
+  MAX_WORKERS="$DEFAULT_MAX_WORKERS"
+  LOCK_TIMEOUT="$DEFAULT_LOCK_TIMEOUT"
 
   # Single config file location: evolution/config.yaml
   local config_file="evolution/config.yaml"
@@ -47,6 +57,7 @@ load_config() {
     echo "[INFO] Loading configuration from: $config_file"
     # Simple YAML parsing for key: value pairs and nested structures
     local in_ideation_section=false
+    local in_parallel_section=false
     while IFS=': ' read -r key value; do
       # Skip comments and empty lines
       [[ $key =~ ^[[:space:]]*# ]] || [[ -z $key ]] && continue
@@ -58,13 +69,19 @@ load_config() {
       # Remove quotes from value
       value=$(echo "$value" | sed 's/^"//;s/"$//')
       
-      # Handle nested ideation_strategies section
+      # Handle nested sections
       if [[ $key == "ideation_strategies" ]]; then
         in_ideation_section=true
+        in_parallel_section=false
+        continue
+      elif [[ $key == "parallel" ]]; then
+        in_parallel_section=true
+        in_ideation_section=false
         continue
-      elif [[ $key =~ ^[a-z_]+ ]] && [[ $in_ideation_section == true ]]; then
-        # Top-level key found, exit ideation section
+      elif [[ $key =~ ^[a-z_]+ ]] && [[ $in_ideation_section == true || $in_parallel_section == true ]]; then
+        # Top-level key found, exit nested sections
         in_ideation_section=false
+        in_parallel_section=false
       fi
       
       if [[ $in_ideation_section == true ]]; then
@@ -77,6 +94,13 @@ load_config() {
           crossover_hybrid) CROSSOVER_HYBRID="$value" ;;
           num_elites) NUM_ELITES="$value" ;;
         esac
+      elif [[ $in_parallel_section == true ]]; then
+        # Handle indented keys in parallel section
+        case $key in
+          enabled) PARALLEL_ENABLED="$value" ;;
+          max_workers) MAX_WORKERS="$value" ;;
+          lock_timeout) LOCK_TIMEOUT="$value" ;;
+        esac
       else
         # Handle top-level keys
         case $key in
@@ -149,6 +173,8 @@ show_config() {
   echo "  CSV file: $FULL_CSV_PATH"
   echo "  Output directory: $FULL_OUTPUT_DIR"
   echo "  Parent selection: $PARENT_SELECTION"
-  echo "  Max ideas: $MAX_IDEAS"
   echo "  Python command: $PYTHON_CMD"
+  echo "  Parallel enabled: $PARALLEL_ENABLED"
+  echo "  Max workers: $MAX_WORKERS"
+  echo "  Lock timeout: $LOCK_TIMEOUT"
 }

package/lib/csv-lock.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# CSV locking functions for parallel execution
+
+# Lock file location
+CSV_LOCKFILE="${EVOLUTION_DIR:-evolution}/.evolution.csv.lock"
+
+# Acquire exclusive lock on CSV file
+# Usage: acquire_csv_lock [timeout_seconds]
+acquire_csv_lock() {
+    local timeout="${1:-30}"
+    local lockdir="$(dirname "$CSV_LOCKFILE")"
+    
+    # Ensure lock directory exists
+    mkdir -p "$lockdir"
+    
+    # Try to acquire lock with timeout
+    if command -v flock >/dev/null 2>&1; then
+        # Use flock if available (Linux)
+        exec 200>"$CSV_LOCKFILE"
+        if ! flock -w "$timeout" -x 200; then
+            echo "ERROR: Failed to acquire CSV lock within $timeout seconds" >&2
+            return 1
+        fi
+    else
+        # Fallback for systems without flock (macOS)
+        local start_time=$(date +%s)
+        while ! (set -C; echo $$ > "$CSV_LOCKFILE") 2>/dev/null; do
+            local current_time=$(date +%s)
+            if [ $((current_time - start_time)) -ge $timeout ]; then
+                echo "ERROR: Failed to acquire CSV lock within $timeout seconds" >&2
+                return 1
+            fi
+            sleep 0.1
+        done
+    fi
+    return 0
+}
+
+# Release CSV lock
+release_csv_lock() {
+    if command -v flock >/dev/null 2>&1; then
+        # Release flock
+        exec 200>&-
+    else
+        # Remove lock file
+        rm -f "$CSV_LOCKFILE"
+    fi
+}
+
+# Read CSV with lock
+# Usage: read_csv_with_lock <variable_name>
+read_csv_with_lock() {
+    local var_name="$1"
+    local csv_file="${EVOLUTION_DIR:-evolution}/evolution.csv"
+    
+    if ! acquire_csv_lock; then
+        return 1
+    fi
+    
+    # Read CSV content
+    if [ -f "$csv_file" ]; then
+        eval "$var_name=\$(cat '$csv_file')"
+    else
+        eval "$var_name=''"
+    fi
+    
+    release_csv_lock
+    return 0
+}
+
+# Write CSV with lock
+# Usage: echo "content" | write_csv_with_lock
+write_csv_with_lock() {
+    local csv_file="${EVOLUTION_DIR:-evolution}/evolution.csv"
+    local temp_file="${csv_file}.tmp.$$"
+    
+    if ! acquire_csv_lock; then
+        return 1
+    fi
+    
+    # Write to temporary file first
+    cat > "$temp_file"
+    
+    # Atomic move
+    mv -f "$temp_file" "$csv_file"
+    
+    release_csv_lock
+    return 0
+}
+
+# Update single CSV row with lock
+# Usage: update_csv_row_with_lock <id> <field> <value>
+update_csv_row_with_lock() {
+    local target_id="$1"
+    local field="$2"
+    local value="$3"
+    local csv_file="${EVOLUTION_DIR:-evolution}/evolution.csv"
+    
+    if ! acquire_csv_lock; then
+        return 1
+    fi
+    
+    # Determine field position
+    local field_pos
+    case "$field" in
+        "status") field_pos=5 ;;
+        "performance") field_pos=4 ;;
+        "description") field_pos=3 ;;
+        "basedOnId") field_pos=2 ;;
+        *) 
+            echo "ERROR: Unknown field: $field" >&2
+            release_csv_lock
+            return 1
+            ;;
+    esac
+    
+    # Update CSV using awk
+    awk -F',' -v OFS=',' -v id="$target_id" -v pos="$field_pos" -v val="$value" '
+        NR==1 || $1 != id { print }
+        $1 == id { $pos = val; print }
+    ' "$csv_file" > "${csv_file}.tmp" && mv -f "${csv_file}.tmp" "$csv_file"
+    
+    release_csv_lock
+    return 0
+}
+
+# Find next pending candidate with lock
+# Usage: next_pending=$(find_next_pending_with_lock)
+find_next_pending_with_lock() {
+    local csv_file="${EVOLUTION_DIR:-evolution}/evolution.csv"
+    
+    if ! acquire_csv_lock; then
+        return 1
+    fi
+    
+    # Find oldest pending candidate and update to running
+    local candidate=$(awk -F',' '
+        NR>1 && $5 == "pending" { print $1; exit }
+    ' "$csv_file")
+    
+    if [ -n "$candidate" ]; then
+        # Update status to running while we have the lock
+        awk -F',' -v OFS=',' -v id="$candidate" '
+            NR==1 || $1 != id { print }
+            $1 == id { $5 = "running"; print }
+        ' "$csv_file" > "${csv_file}.tmp" && mv -f "${csv_file}.tmp" "$csv_file"
+    fi
+    
+    release_csv_lock
+    echo "$candidate"
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "claude-evolve",
-  "version": "1.2.13",
+  "version": "1.3.0",
   "bin": {
     "claude-evolve": "./bin/claude-evolve",
     "claude-evolve-main": "./bin/claude-evolve-main",
     "claude-evolve-setup": "./bin/claude-evolve-setup",
     "claude-evolve-ideate": "./bin/claude-evolve-ideate",
     "claude-evolve-run": "./bin/claude-evolve-run",
+    "claude-evolve-run-parallel": "./bin/claude-evolve-run-parallel",
+    "claude-evolve-worker": "./bin/claude-evolve-worker",
     "claude-evolve-analyze": "./bin/claude-evolve-analyze",
     "claude-evolve-config": "./bin/claude-evolve-config"
   },

package/templates/config.yaml

@@ -35,4 +35,15 @@ ideation_strategies:
   num_elites: 3
 
 # Python command to use for evaluation
-python_cmd: "python3"
+python_cmd: "python3"
+
+# Parallel execution configuration
+parallel:
+  # Enable parallel execution of evolution candidates
+  enabled: false
+  
+  # Maximum number of worker processes to run simultaneously
+  max_workers: 4
+  
+  # Timeout in seconds when waiting for CSV locks
+  lock_timeout: 30