claude-evolve 1.0.0

package/BRIEF.md

@@ -0,0 +1,41 @@
+# Project Brief
+
+## Vision
+
+We've been very excited by the possibilities and demonstrated performance of AlphaEvolve, and the potential
+of OpenEvolve, a clone of AlphaEvolve. However, in testing, it hasn't worked super well, at least for design
+of neural network architectures. It tended to evolve very slowly, and get caught up in local minima.
+
+We would like to like to try a new idea, based on the success of the claude-fsd approach (in
+../claude-fsd for reference). The claude-fsd package is a npm package based on simple shell scripts
+that leans on `claude -p` to call the Claude Code coder to perform workhorse functions like planning,
+architecting, and running a plan-develop-test loop until the projet is done. So with this `claude-evolve`
+variant, we take the same approach for develop, but this is for algorithm development, using a
+plan-develop-run-record loop, running test after test and recording the quantitative results, all
+the while providing the human operator the opportunity to fill the tail end of the ideas pipeline
+using `claude-evolve ideate` or just interactive conversations with an AI, or editing the file
+directly.
+
+## Core Requirements
+
+Commands:
+
+- claude-evolve -- runs a menu like with claude-fsd
+- claude-evolve setup -- sets up the baseline evolution/ files if they're not present, and allows for editing the brief
+- claude-evolve ideate [50] -- takes user input and launches `claude -p` to generate [param] new ideas
+- claude-evolve run -- runs the plan-develop-run-record loop
+- claude-evolve analyze -- shows a chart of performance and performance changes over time, and highlights the top candidate so far
+
+Files:
+
+- evolution/BRIEF.md -- a description of what the project is about and the goals of the thing to be evolved, as well as identifying the evolving algo baseline file and the evaluator file
+- evolution/evolution.csv -- a list of all iterations, with columns ID,basedonID,description,performance,status
+- evolution/evolution_details.md -- a description, for each ID, of the details of what should be changed or what did change, any commentary about the design or the performance, etc., all of which is optional
+- evolution/evolution_id[id].py -- a copy of the tested algo version at that ID
+
+The evaluator file takes the name of the file to test as its one argument, and outputs a dictionary with one performance metric as the output.
+
+## Success Criteria
+
+- Success criterion 1
+- Success criterion 2

package/bin/claude-evolve

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+# Main dispatcher script for claude-evolve
+exec "$(dirname "$0")/claude-evolve-main" "$@"

package/bin/claude-evolve-analyze

@@ -0,0 +1,173 @@
+#!/bin/bash
+
+set -e
+
+# Parse arguments
+open_chart=false
+csv_file="evolution/evolution.csv"
+output_file="evolution/performance.png"
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  --help)
+    cat <<EOF
+claude-evolve analyze - Analyze evolution results
+
+USAGE:
+  claude-evolve analyze [--open] [--csv <path>] [--output <path>]
+
+OPTIONS:
+  --open            Open the generated chart automatically
+  --csv <path>      Path to evolution.csv (default: ./evolution/evolution.csv)
+  --output <path>   Output path for chart PNG (default: ./evolution/performance.png)
+  --help            Show this help message
+
+DESCRIPTION:
+  Analyzes the evolution.csv file and generates a performance chart.
+  Displays summary statistics and identifies the top performing algorithm.
+EOF
+    exit 0
+    ;;
+  --open)
+    open_chart=true
+    shift
+    ;;
+  --csv)
+    csv_file="$2"
+    shift 2
+    ;;
+  --output)
+    output_file="$2"
+    shift 2
+    ;;
+  *)
+    echo "[ERROR] Unknown option: $1" >&2
+    exit 1
+    ;;
+  esac
+done
+
+# Check if CSV exists
+if [[ ! -f $csv_file ]]; then
+  echo "[ERROR] CSV file not found: $csv_file" >&2
+  echo "[ERROR] Run 'claude-evolve setup' and 'claude-evolve ideate' first." >&2
+  exit 1
+fi
+
+echo "=== Evolution Analysis Summary ==="
+echo
+
+# Count totals (pure shell)
+total=0
+completed=0
+running=0
+failed=0
+pending=0
+total_performance=0
+count_with_performance=0
+top_score=""
+top_id=""
+top_desc=""
+
+while IFS=, read -r id _ desc perf status; do
+  [[ $id == "id" ]] && continue # Skip header
+
+  ((total++))
+
+  case "$status" in
+  "completed") ((completed++)) ;;
+  "running") ((running++)) ;;
+  "failed" | "timeout" | "interrupted") ((failed++)) ;;
+  *) ((pending++)) ;;
+  esac
+
+  # Track performance stats
+  if [[ -n $perf && $perf != "" ]]; then
+    total_performance=$(echo "$total_performance + $perf" | bc -l 2>/dev/null || echo "$total_performance")
+    ((count_with_performance++))
+
+    # Check if this is the top performer
+    if [[ -z $top_score ]] || (($(echo "$perf > $top_score" | bc -l 2>/dev/null || echo "0"))); then
+      top_score="$perf"
+      top_id="$id"
+      top_desc="$desc"
+    fi
+  fi
+done <"$csv_file"
+
+# Display summary
+echo "Total Candidates: $total"
+echo "Completed: $completed"
+echo "Running: $running"
+echo "Failed: $failed"
+echo "Pending: $pending"
+
+if [[ $count_with_performance -gt 0 ]]; then
+  avg_performance=$(echo "scale=4; $total_performance / $count_with_performance" | bc -l 2>/dev/null || echo "0")
+  echo "Average Performance: $avg_performance"
+else
+  echo "Average Performance: N/A"
+fi
+
+echo
+echo "=== Top Performer ==="
+if [[ -n $top_id ]]; then
+  echo "ID: $top_id"
+  echo "Performance: $top_score"
+  echo "Description: $top_desc"
+else
+  echo "No completed candidates yet"
+fi
+
+# Simple chart generation using gnuplot if available
+if command -v gnuplot >/dev/null 2>&1 && [[ $count_with_performance -gt 0 ]]; then
+  echo
+  echo "Generating performance chart: $output_file"
+
+  # Create data file for gnuplot
+  data_file="/tmp/evolution_data_$$.dat"
+  echo "# ID Performance" >"$data_file"
+
+  while IFS=, read -r id _ desc perf status; do
+    [[ $id == "id" ]] && continue # Skip header
+    if [[ -n $perf && $perf != "" ]]; then
+      echo "$id $perf" >>"$data_file"
+    fi
+  done <"$csv_file"
+
+  # Generate plot
+  gnuplot <<EOF
+set terminal png size 800,600
+set output "$output_file"
+set title "Algorithm Evolution Performance"
+set xlabel "Evolution ID"
+set ylabel "Performance Score"
+set grid
+plot "$data_file" using 1:2 with linespoints title "Performance"
+EOF
+
+  rm -f "$data_file"
+  echo "Chart saved successfully!"
+
+  # Open chart if requested
+  if [[ $open_chart == true ]]; then
+    if command -v open >/dev/null 2>&1; then
+      open "$output_file"
+    elif command -v xdg-open >/dev/null 2>&1; then
+      xdg-open "$output_file"
+    else
+      echo "[WARN] Cannot open chart automatically. View: $output_file"
+    fi
+  fi
+else
+  if [[ $count_with_performance -eq 0 ]]; then
+    echo
+    echo "No performance data available for chart generation."
+    echo "Run 'claude-evolve run' to execute candidates first."
+  else
+    echo
+    echo "[WARN] gnuplot not found. Install gnuplot for chart generation."
+    echo "       On macOS: brew install gnuplot"
+    echo "       On Ubuntu: sudo apt install gnuplot"
+  fi
+fi

package/bin/claude-evolve-ideate

@@ -0,0 +1,206 @@
+#!/bin/bash
+
+set -e
+
+# Parse arguments
+count=1
+no_ai=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+  --help)
+    cat <<EOF
+claude-evolve ideate - Generate new algorithm ideas
+
+USAGE:
+  claude-evolve ideate [N] [--no-ai]
+
+ARGUMENTS:
+  N         Number of ideas to generate (default: 1, max: 50)
+
+OPTIONS:
+  --no-ai   Use manual entry mode instead of AI generation
+  --help    Show this help message
+
+DESCRIPTION:
+  Generates new algorithm variations by prompting Claude with context
+  from the project BRIEF.md and top performers from evolution.csv.
+  Falls back to manual entry if --no-ai is specified or Claude fails.
+EOF
+    exit 0
+    ;;
+  --no-ai)
+    no_ai=true
+    shift
+    ;;
+  *)
+    if [[ $1 =~ ^[0-9]+$ ]]; then
+      count=$1
+    else
+      echo "[ERROR] Invalid number of ideas: $1" >&2
+      exit 1
+    fi
+    shift
+    ;;
+  esac
+done
+
+# Validate count
+if [[ $count -lt 1 || $count -gt 50 ]]; then
+  echo "[ERROR] Number of ideas must be between 1 and 50" >&2
+  exit 1
+fi
+
+# Check workspace
+if [[ ! -d evolution ]]; then
+  echo "[ERROR] Evolution workspace not found. Run 'claude-evolve setup' first." >&2
+  exit 1
+fi
+
+# Ensure CSV exists
+if [[ ! -f evolution/evolution.csv ]]; then
+  echo "id,basedOnId,description,performance,status" >evolution/evolution.csv
+fi
+
+# Get next ID
+get_next_id() {
+  if [[ ! -f evolution/evolution.csv ]]; then
+    echo "1"
+    return
+  fi
+  # Find highest ID and increment (pure shell)
+  local max_id=0
+  while IFS=, read -r id rest; do
+    if [[ $id =~ ^[0-9]+$ ]] && [[ $id -gt $max_id ]]; then
+      max_id=$id
+    fi
+  done < <(tail -n +2 evolution/evolution.csv)
+  echo $((max_id + 1))
+}
+
+# Add idea to CSV
+add_idea() {
+  local description="$1"
+  local id
+  id=$(get_next_id)
+
+  # Escape quotes in description
+  local escaped_desc="${description//\"/\"\"}"
+
+  # Append to CSV
+  echo "${id},,\"${escaped_desc}\",," >>evolution/evolution.csv
+  echo "[INFO] Added idea: $description"
+}
+
+# Manual entry mode
+ideate_manual() {
+  local ideas_added=0
+
+  for ((i = 1; i <= count; i++)); do
+    if [[ $count -eq 1 ]]; then
+      read -r -p "Enter algorithm idea (or empty to skip): " description
+    else
+      read -r -p "Enter algorithm idea $i/$count (or empty to skip): " description
+    fi
+
+    if [[ -z $description ]]; then
+      echo "[INFO] Empty description, skipping idea"
+      continue
+    fi
+
+    add_idea "$description"
+    ((ideas_added++))
+
+    if [[ $i -lt $count ]]; then
+      read -r -p "Add another idea? (y/N) " continue_adding
+      if [[ $continue_adding != "y" && $continue_adding != "Y" ]]; then
+        break
+      fi
+    fi
+  done
+
+  echo "[INFO] Added $ideas_added idea(s) to evolution.csv"
+}
+
+# AI generation mode
+ideate_ai() {
+  # Check for claude CLI
+  if ! command -v claude >/dev/null 2>&1; then
+    echo "[WARN] Claude CLI not found. Falling back to manual entry."
+    return 1
+  fi
+
+  if [[ ! -f evolution/BRIEF.md ]]; then
+    echo "[WARN] BRIEF.md not found. Falling back to manual entry."
+    return 1
+  fi
+
+  # Get top performers (pure shell)
+  local top_performers=""
+  if [[ -f evolution/evolution.csv ]]; then
+    # Simple top performers extraction (lines with non-empty performance)
+    top_performers=$(awk -F, 'NR > 1 && $4 != "" { print $1 ": " $3 " (score: " $4 ")" }' evolution/evolution.csv | head -5)
+  fi
+
+  # Build prompt
+  local prompt
+  prompt="You are helping with algorithm evolution. Generate exactly $count new algorithm idea(s) based on the following context.
+
+Project Brief:
+$(cat evolution/BRIEF.md)
+"
+
+  if [[ -n $top_performers ]]; then
+    prompt+="
+Top Performing Algorithms So Far:
+$top_performers
+"
+  fi
+
+  prompt+="
+Generate $count creative algorithm variation(s) that could potentially improve performance.
+For each idea, provide a single line description that explains the approach.
+Format: One idea per line, no numbering, no extra formatting."
+
+  echo "[INFO] Generating $count idea(s) with Claude..."
+
+  # Call Claude and process response
+  local response
+  if ! response=$(echo "$prompt" | claude -p 2>&1); then
+    echo "[WARN] Claude API call failed, falling back to manual entry."
+    return 1
+  fi
+
+  local ideas_added=0
+  while IFS= read -r line; do
+    # Clean up line
+    line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    [[ -z $line ]] && continue
+
+    # Remove numbering/bullets
+    line=$(echo "$line" | sed 's/^[0-9]*\. *//;s/^[-*] *//')
+
+    add_idea "$line"
+    ((ideas_added++))
+
+    [[ $ideas_added -ge $count ]] && break
+  done <<<"$response"
+
+  if [[ $ideas_added -eq 0 ]]; then
+    echo "[WARN] No valid ideas extracted from Claude response"
+    return 1
+  fi
+
+  echo "[INFO] Successfully generated $ideas_added idea(s)"
+}
+
+# Main execution
+if [[ $no_ai == true ]]; then
+  echo "[INFO] Manual entry mode"
+  ideate_manual
+else
+  if ! ideate_ai; then
+    echo "[INFO] Falling back to manual entry"
+    ideate_manual
+  fi
+fi

package/bin/claude-evolve-main

@@ -0,0 +1,126 @@
+#!/bin/bash
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Get version from package.json
+get_version() {
+  if [[ -f "$PROJECT_ROOT/package.json" ]]; then
+    grep '"version"' "$PROJECT_ROOT/package.json" | sed 's/.*"version": *"\([^"]*\)".*/\1/'
+  else
+    echo "unknown"
+  fi
+}
+
+
+show_help() {
+  cat <<EOF
+claude-evolve - AI-powered algorithm evolution tool
+
+USAGE:
+    claude-evolve [COMMAND] [OPTIONS]
+
+COMMANDS:
+    setup       Initialize evolution workspace
+    ideate      Generate new algorithm ideas
+    run         Execute evolution candidates
+    analyze     Analyze evolution results
+    help        Show this help message
+
+OPTIONS:
+    -h, --help     Show help message
+    -v, --version  Show version
+
+EXAMPLES:
+    claude-evolve setup
+    claude-evolve ideate 5
+    claude-evolve run --timeout 300
+    claude-evolve analyze --open
+
+For more information, visit: https://github.com/anthropics/claude-evolve
+EOF
+}
+
+show_menu() {
+  echo -e "${GREEN}🧬 Claude Evolve - Algorithm Evolution Tool${NC}"
+  echo
+  echo "This tool helps you evolve algorithms using AI-powered mutations."
+  echo
+  echo "What would you like to do?"
+  echo
+  echo "  1) setup    - Initialize evolution workspace"
+  echo "  2) ideate   - Generate new algorithm ideas"
+  echo "  3) run      - Execute evolution candidates"
+  echo "  4) analyze  - Analyze evolution results"
+  echo "  5) help     - Show help message"
+  echo "  6) exit     - Exit"
+  echo
+
+  # Show workspace status
+  echo "Current status:"
+  [[ -d evolution ]] && echo "  ✓ evolution/ workspace exists" || echo "  ✗ evolution/ workspace missing"
+  [[ -f evolution/BRIEF.md ]] && echo "  ✓ BRIEF.md exists" || echo "  ✗ BRIEF.md missing"
+  [[ -f evolution/evolution.csv ]] && echo "  ✓ evolution.csv exists" || echo "  ✗ evolution.csv missing"
+  echo
+}
+
+# Main logic
+if [[ $# -eq 0 ]]; then
+  show_menu
+  read -r -p "Enter your choice (1-6): " choice
+
+  case $choice in
+  1) exec "$SCRIPT_DIR/claude-evolve-setup" ;;
+  2) exec "$SCRIPT_DIR/claude-evolve-ideate" ;;
+  3) exec "$SCRIPT_DIR/claude-evolve-run" ;;
+  4) exec "$SCRIPT_DIR/claude-evolve-analyze" ;;
+  5) show_help ;;
+  6)
+    echo "Goodbye!"
+    exit 0
+    ;;
+  *)
+    echo -e "${RED}Invalid choice. Please select 1-6.${NC}"
+    exit 1
+    ;;
+  esac
+fi
+
+case "${1:-}" in
+-h | --help | help)
+  show_help
+  ;;
+-v | --version)
+  echo "claude-evolve v$(get_version)"
+  ;;
+setup)
+  shift
+  exec "$SCRIPT_DIR/claude-evolve-setup" "$@"
+  ;;
+ideate)
+  shift
+  exec "$SCRIPT_DIR/claude-evolve-ideate" "$@"
+  ;;
+run)
+  shift
+  exec "$SCRIPT_DIR/claude-evolve-run" "$@"
+  ;;
+analyze)
+  shift
+  exec "$SCRIPT_DIR/claude-evolve-analyze" "$@"
+  ;;
+*)
+  echo "Unknown command: ${1:-}"
+  echo
+  show_help
+  exit 1
+  ;;
+esac