claude-evolve 1.0.8 → 1.0.10

package/README.md

@@ -0,0 +1,202 @@
+# claude-evolve
+
+Automated algorithm evolution - let AI evolve your algorithms while you sleep.
+
+## What is this?
+
+claude-evolve is an automated algorithm evolution system that runs continuous evolution cycles without constant supervision. Start with a base algorithm and let it evolve optimized variants autonomously.
+
+Think of it like **genetic algorithms for code** - it handles the mutations and testing, but you should keep an eye on the results and occasionally guide the evolution when needed.
+
+### How the Evolution System Works
+
+The system operates with specialized phases working together:
+
+- 🧠 **Ideation Phase**: Generates creative algorithm variations using Claude Opus
+- 🔬 **Development Phase**: Implements mutations using Claude Sonnet (with periodic Opus "megathinking")
+- 📊 **Evaluation Phase**: Tests performance against your custom evaluator
+- 📈 **Analysis Phase**: Tracks evolution progress and identifies top performers
+
+The evolution cycle:
+```
+Ideate → Mutate → Evaluate → Analyze → Repeat
+```
+
+You can leave it running while you grab lunch or sleep - it just keeps evolving better algorithms until you stop it.
+
+## Installation
+
+```bash
+npm install -g claude-evolve
+```
+
+## Quick Start
+
+```bash
+claude-evolve
+```
+
+The system will walk you through the setup process:
+
+1. **Create evolution workspace** - Initialize the directory structure
+2. **Write evolution/BRIEF.md** - Describe your optimization problem
+3. **Customize evolution/evaluator.py** - Define how to measure algorithm performance
+4. **Generate ideas** - Create initial algorithm candidates
+5. **Start evolution** - Begin the automated evolution process
+
+## Commands
+
+### Main wrapper command
+```bash
+claude-evolve        # Interactive mode (recommended for beginners)
+claude-evolve setup  # Initialize evolution workspace
+claude-evolve ideate # Generate new algorithm ideas
+claude-evolve run    # Execute evolution candidates
+claude-evolve analyze # Analyze evolution results
+claude-evolve config # Manage configuration settings
+```
+
+### Individual commands (if you know what you're doing)
+
+#### claude-evolve-setup
+Initializes your evolution workspace with:
+- Directory structure
+- Template files (BRIEF.md, algorithm.py, evaluator.py, config.yaml)
+- CSV file for tracking evolution progress
+
+#### claude-evolve-ideate
+Generates new algorithm variation ideas using Claude Opus in megathinking mode:
+- Reads your project brief
+- Analyzes top-performing algorithms so far
+- Creates creative mutations and variations
+- Defaults to 20 ideas per run (configurable)
+
+#### claude-evolve-run
+Executes the next evolution candidate:
+- Picks the next untested idea from your CSV
+- Uses Claude to implement the mutation
+- Runs your evaluator to measure performance
+- Records results and updates the evolution log
+- Every 4th iteration uses Opus for architectural thinking
+
+#### claude-evolve-analyze
+Analyzes evolution progress and generates insights:
+- Performance trends over time
+- Best-performing algorithm variants
+- Suggestions for future evolution directions
+
+#### claude-evolve-config
+Manages configuration settings:
+- View current configuration
+- Edit paths and behavior settings
+- Reset to defaults
+
+## How it Works
+
+1. **Set up evolution workspace** - Define your optimization problem
+2. **Create base algorithm** - Start with `evolution/algorithm.py`
+3. **Define evaluation criteria** - Customize `evolution/evaluator.py`
+4. **Generate initial ideas** - Run `claude-evolve ideate` to create variations
+5. **Start evolution loop** - The system automatically:
+   - Picks the next candidate from your CSV
+   - Implements the mutation
+   - Evaluates performance
+   - Records results
+   - Repeats until you stop it
+
+## Monitoring Progress (Like Genetic Algorithms)
+
+This isn't sci-fi level "sleep through the entire evolution" automation - it's more like controlled genetic algorithms. The system handles most mutations, but you should monitor it and guide the evolution when needed.
+
+**Recommended monitoring approach:**
+- **Check evolution.csv** - Track performance of all variants
+- **Review top performers** - Look at the best algorithms generated so far
+- **Monitor for convergence** - Watch for diminishing returns or local optima
+- **Inject new ideas** - Add manual variations when evolution stagnates
+
+**When you need to guide evolution:**
+- **Add targeted ideas** - Use `claude-evolve ideate` with specific directions
+- **Modify the evaluator** - Update `evolution/evaluator.py` to change selection pressure
+- **Restart from best** - Copy top performer to `algorithm.py` and continue evolving
+- **The system adapts** - New ideas will build on your guidance
+
+**Interruptible design:**
+- Hit Ctrl+C anytime to pause
+- Restart later with `claude-evolve run`
+- Perfect for running overnight, during meetings, or while getting lunch
+
+## Requirements
+
+### Required
+- Node.js >= 14.0.0
+- Python 3.x (for algorithm execution)
+- Unix-like environment (macOS, Linux)
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
+
+### Optional (but recommended)
+- Scientific Python libraries (numpy, scipy, etc.) depending on your algorithms
+- Plotting libraries (matplotlib, plotly) for analyzing results
+
+## Project Structure
+
+Your evolution workspace will have:
+```
+your-project/
+├── evolution/
+│   ├── BRIEF.md           # Problem description and goals
+│   ├── algorithm.py       # Base algorithm to evolve
+│   ├── evaluator.py       # Performance evaluation logic
+│   ├── config.yaml        # Configuration settings
+│   ├── evolution.csv      # Evolution progress tracking
+│   ├── evolution_id1.py   # Generated algorithm variants
+│   ├── evolution_id2.py
+│   └── ...
+└── (your main project files)
+```
+
+## Configuration
+
+Edit `evolution/config.yaml` to customize:
+
+```yaml
+# Working directory for evolution files
+evolution_dir: "evolution"
+
+# Algorithm and evaluator file paths
+algorithm_file: "algorithm.py"
+evaluator_file: "evaluator.py"
+brief_file: "BRIEF.md"
+
+# CSV file for tracking evolution
+evolution_csv: "evolution.csv"
+
+# Parent algorithm selection strategy
+parent_selection: "best"  # or "random", "latest"
+
+# Maximum number of ideas to generate at once
+max_ideas: 50
+
+# Python command to use for evaluation
+python_cmd: "python3"
+```
+
+## Tips for Success
+
+1. **Write a clear BRIEF.md** - Describe your optimization problem, constraints, and goals
+2. **Create a robust evaluator** - Your evaluator.py determines evolution direction
+3. **Start simple** - Begin with a basic algorithm and let evolution add complexity
+4. **Monitor early cycles** - Watch the first few evolutions to ensure proper setup
+5. **Guide when stuck** - Add manual ideas when evolution hits local optima
+6. **Embrace failures** - Not every mutation will be better, that's how evolution works
+
+## Example Use Cases
+
+- **Algorithm optimization** - Improve sorting, searching, or mathematical algorithms
+- **Machine learning** - Evolve model architectures or training procedures
+- **Game AI** - Develop and optimize game-playing strategies
+- **Numerical methods** - Improve solvers, optimizers, or approximation algorithms
+- **Data structures** - Evolve efficient data organization strategies
+
+## License
+
+MIT

package/bin/claude-evolve-config

@@ -24,11 +24,9 @@ DESCRIPTION:
   Manages claude-evolve configuration settings including file paths,
   algorithm locations, and behavior settings.
 
-CONFIGURATION FILES:
-  The configuration is loaded from the first file found:
-  1. ./config.sh (current directory)
-  2. ./evolution/config.sh (evolution workspace)
-  3. ./.claude-evolve.config (hidden config file)
+CONFIGURATION FILE:
+  The configuration is loaded from:
+  evolution/config.yaml
 
   If no config file exists, defaults are used.
 EOF
@@ -70,54 +68,33 @@ show)
   show_config
   ;;
 edit)
-  # Find or create config file
-  config_file=""
-  if [[ -f "evolution/config.sh" ]]; then
-    config_file="evolution/config.sh"
-  elif [[ -f "config.sh" ]]; then
-    config_file="config.sh"
-  elif [[ -f ".claude-evolve.config" ]]; then
-    config_file=".claude-evolve.config"
-  else
-    # Create in evolution directory if it exists
-    if [[ -d "evolution" ]]; then
-      config_file="evolution/config.sh"
-    else
-      config_file="config.sh"
+  # Single config file location
+  config_file="evolution/config.yaml"
+  
+  if [[ ! -f "$config_file" ]]; then
+    if [[ ! -d "evolution" ]]; then
+      echo "[ERROR] Evolution directory not found. Run 'claude-evolve setup' first." >&2
+      exit 1
     fi
+    
     echo "[INFO] Creating new config file: $config_file"
     
     # Copy template if available
-    if [[ -f "$SCRIPT_DIR/../templates/config.sh" ]]; then
-      cp "$SCRIPT_DIR/../templates/config.sh" "$config_file"
+    if [[ -f "$SCRIPT_DIR/../templates/config.yaml" ]]; then
+      cp "$SCRIPT_DIR/../templates/config.yaml" "$config_file"
     else
       # Create basic config
       cat > "$config_file" <<EOF
-#!/bin/bash
 # claude-evolve configuration file
-
-# Working directory for evolution files
-EVOLUTION_DIR="evolution"
-
-# Algorithm and evaluator file paths (relative to EVOLUTION_DIR)
-ALGORITHM_FILE="algorithm.py"
-EVALUATOR_FILE="evaluator.py"
-BRIEF_FILE="BRIEF.md"
-
-# CSV file for tracking evolution (relative to EVOLUTION_DIR)
-EVOLUTION_CSV="evolution.csv"
-
-# Output directory for generated algorithms (relative to EVOLUTION_DIR)
-OUTPUT_DIR=""
-
-# Parent algorithm selection strategy: "best", "random", "latest"
-PARENT_SELECTION="best"
-
-# Maximum number of ideas to generate at once
-MAX_IDEAS=50
-
-# Python command to use for evaluation
-PYTHON_CMD="python3"
+evolution_dir: "evolution"
+algorithm_file: "algorithm.py"
+evaluator_file: "evaluator.py"
+brief_file: "BRIEF.md"
+evolution_csv: "evolution.csv"
+output_dir: ""
+parent_selection: "best"
+max_ideas: 50
+python_cmd: "python3"
 EOF
     fi
   fi
@@ -135,43 +112,29 @@ EOF
   fi
   ;;
 reset)
-  if [[ -d "evolution" ]]; then
-    config_file="evolution/config.sh"
-  else
-    config_file="config.sh"
+  config_file="evolution/config.yaml"
+  
+  if [[ ! -d "evolution" ]]; then
+    echo "[ERROR] Evolution directory not found. Run 'claude-evolve setup' first." >&2
+    exit 1
   fi
   
   echo "[INFO] Resetting configuration to defaults: $config_file"
-  if [[ -f "$SCRIPT_DIR/../templates/config.sh" ]]; then
-    cp "$SCRIPT_DIR/../templates/config.sh" "$config_file"
+  if [[ -f "$SCRIPT_DIR/../templates/config.yaml" ]]; then
+    cp "$SCRIPT_DIR/../templates/config.yaml" "$config_file"
   else
     # Create default config
     cat > "$config_file" <<EOF
-#!/bin/bash
 # claude-evolve configuration file
-
-# Working directory for evolution files
-EVOLUTION_DIR="evolution"
-
-# Algorithm and evaluator file paths (relative to EVOLUTION_DIR)  
-ALGORITHM_FILE="algorithm.py"
-EVALUATOR_FILE="evaluator.py"
-BRIEF_FILE="BRIEF.md"
-
-# CSV file for tracking evolution (relative to EVOLUTION_DIR)
-EVOLUTION_CSV="evolution.csv"
-
-# Output directory for generated algorithms (relative to EVOLUTION_DIR)
-OUTPUT_DIR=""
-
-# Parent algorithm selection strategy: "best", "random", "latest"
-PARENT_SELECTION="best"
-
-# Maximum number of ideas to generate at once
-MAX_IDEAS=50
-
-# Python command to use for evaluation
-PYTHON_CMD="python3"
+evolution_dir: "evolution"
+algorithm_file: "algorithm.py"
+evaluator_file: "evaluator.py"
+brief_file: "BRIEF.md"
+evolution_csv: "evolution.csv"
+output_dir: ""
+parent_selection: "best"
+max_ideas: 50
+python_cmd: "python3"
 EOF
   fi
   echo "[INFO] Configuration reset successfully"

package/bin/claude-evolve-setup

@@ -20,7 +20,7 @@ else
 fi
 
 # Copy template files
-for file in BRIEF.md algorithm.py evaluator.py config.sh; do
+for file in BRIEF.md algorithm.py evaluator.py config.yaml; do
   if [[ ! -f evolution/$file ]]; then
     if [[ -f "$PROJECT_ROOT/templates/$file" ]]; then
       echo "[INFO] Copying $file from templates..."

package/lib/config.sh

@@ -25,21 +25,36 @@ load_config() {
   MAX_IDEAS="$DEFAULT_MAX_IDEAS"
   PYTHON_CMD="$DEFAULT_PYTHON_CMD"
 
-  # Look for config file in current directory, then evolution directory
-  local config_file=""
-  if [[ -f "config.sh" ]]; then
-    config_file="config.sh"
-  elif [[ -f "evolution/config.sh" ]]; then
-    config_file="evolution/config.sh"
-  elif [[ -f ".claude-evolve.config" ]]; then
-    config_file=".claude-evolve.config"
-  fi
-
+  # Single config file location: evolution/config.yaml
+  local config_file="evolution/config.yaml"
+  
   # Load config if found
-  if [[ -n $config_file ]]; then
+  if [[ -f "$config_file" ]]; then
     echo "[INFO] Loading configuration from: $config_file"
-    # shellcheck source=/dev/null
-    source "$config_file"
+    # Simple YAML parsing for key: value pairs
+    while IFS=': ' read -r key value; do
+      # Skip comments and empty lines
+      [[ $key =~ ^[[:space:]]*# ]] || [[ -z $key ]] && continue
+      
+      # Remove leading/trailing whitespace
+      key=$(echo "$key" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+      value=$(echo "$value" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+      
+      # Remove quotes from value
+      value=$(echo "$value" | sed 's/^"//;s/"$//')
+      
+      case $key in
+        evolution_dir) EVOLUTION_DIR="$value" ;;
+        algorithm_file) ALGORITHM_FILE="$value" ;;
+        evaluator_file) EVALUATOR_FILE="$value" ;;
+        brief_file) BRIEF_FILE="$value" ;;
+        evolution_csv) EVOLUTION_CSV="$value" ;;
+        output_dir) OUTPUT_DIR="$value" ;;
+        parent_selection) PARENT_SELECTION="$value" ;;
+        max_ideas) MAX_IDEAS="$value" ;;
+        python_cmd) PYTHON_CMD="$value" ;;
+      esac
+    done < "$config_file"
   fi
 
   # Create full paths

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-evolve",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "bin": {
     "claude-evolve": "./bin/claude-evolve",
     "claude-evolve-main": "./bin/claude-evolve-main",

package/templates/config.yaml

@@ -0,0 +1,27 @@
+# claude-evolve configuration file
+# This file defines paths and settings for the evolution process
+
+# Working directory for evolution files
+evolution_dir: "evolution"
+
+# Algorithm and evaluator file paths (relative to evolution_dir)
+algorithm_file: "algorithm.py"
+evaluator_file: "evaluator.py"
+brief_file: "BRIEF.md"
+
+# CSV file for tracking evolution (relative to evolution_dir)
+evolution_csv: "evolution.csv"
+
+# Output directory for generated algorithms (relative to evolution_dir)
+# Leave empty to use evolution_dir directly
+output_dir: ""
+
+# Parent algorithm selection strategy
+# Options: "best", "random", "latest"
+parent_selection: "best"
+
+# Maximum number of ideas to generate at once
+max_ideas: 50
+
+# Python command to use for evaluation
+python_cmd: "python3"

package/templates/config.sh

@@ -1,27 +0,0 @@
-#!/bin/bash
-# claude-evolve configuration file
-# This file defines paths and settings for the evolution process
-
-# Working directory for evolution files
-EVOLUTION_DIR="evolution"
-
-# Algorithm and evaluator file paths (relative to EVOLUTION_DIR)
-ALGORITHM_FILE="algorithm.py"
-EVALUATOR_FILE="evaluator.py"
-BRIEF_FILE="BRIEF.md"
-
-# CSV file for tracking evolution (relative to EVOLUTION_DIR)
-EVOLUTION_CSV="evolution.csv"
-
-# Output directory for generated algorithms (relative to EVOLUTION_DIR)
-OUTPUT_DIR=""
-
-# Parent algorithm selection strategy
-# Options: "best", "random", "latest"
-PARENT_SELECTION="best"
-
-# Maximum number of ideas to generate at once
-MAX_IDEAS=50
-
-# Python command to use for evaluation
-PYTHON_CMD="python3"