claude-evolve 1.0.9 → 1.0.11

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-analyze

@@ -2,10 +2,16 @@
 
 set -e
 
+# Load configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/config.sh
+source "$SCRIPT_DIR/../lib/config.sh"
+load_config
+
 # Parse arguments
 open_chart=false
-csv_file="evolution/evolution.csv"
-output_file="evolution/performance.png"
+csv_file="$FULL_CSV_PATH"
+output_file="$FULL_OUTPUT_DIR/performance.png"
 
 while [[ $# -gt 0 ]]; do
   case $1 in

package/bin/claude-evolve-run

@@ -2,6 +2,12 @@
 
 set -e
 
+# Load configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/config.sh
+source "$SCRIPT_DIR/../lib/config.sh"
+load_config
+
 # Parse arguments
 timeout_seconds=""
 
@@ -46,18 +52,27 @@ done
 echo "[INFO] Starting evolution run..."
 [[ -n $timeout_seconds ]] && echo "[INFO] Using timeout: ${timeout_seconds} seconds"
 
-# Validate workspace
-if [[ ! -d evolution ]]; then
-  echo "[ERROR] Evolution directory not found. Run 'claude-evolve setup' first." >&2
+# Validate workspace using config
+if [[ ! -d "$FULL_EVOLUTION_DIR" ]]; then
+  echo "[ERROR] Evolution directory not found: $FULL_EVOLUTION_DIR. Run 'claude-evolve setup' first." >&2
   exit 1
 fi
 
-for file in evolution.csv evaluator.py; do
-  if [[ ! -f evolution/$file ]]; then
-    echo "[ERROR] $file not found. Run 'claude-evolve setup' first." >&2
-    exit 1
-  fi
-done
+# Check required files
+if [[ ! -f "$FULL_CSV_PATH" ]]; then
+  echo "[ERROR] CSV file not found: $FULL_CSV_PATH" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FULL_EVALUATOR_PATH" ]]; then
+  echo "[ERROR] Evaluator not found: $FULL_EVALUATOR_PATH" >&2
+  exit 1
+fi
+
+if [[ ! -f "$FULL_ALGORITHM_PATH" ]]; then
+  echo "[ERROR] Algorithm not found: $FULL_ALGORITHM_PATH" >&2
+  exit 1
+fi
 
 # Find oldest empty row (pure shell)
 find_empty_row() {
@@ -68,13 +83,13 @@ find_empty_row() {
       return 0
     fi
     ((row_num++))
-  done < <(tail -n +2 evolution/evolution.csv)
+  done < <(tail -n +2 "$FULL_CSV_PATH")
   return 1
 }
 
 # Get CSV row (pure shell)
 get_csv_row() {
-  sed -n "${1}p" evolution/evolution.csv
+  sed -n "${1}p" "$FULL_CSV_PATH"
 }
 
 # Update CSV row (pure shell with temp file)
@@ -84,7 +99,7 @@ update_csv_row() {
   local status="$3"
 
   # Read CSV and update specific row
-  local temp_file="evolution/evolution.csv.tmp"
+  local temp_file="${FULL_CSV_PATH}.tmp"
   local current_row=1
 
   while IFS=, read -r id based_on desc perf stat; do
@@ -96,9 +111,9 @@ update_csv_row() {
       echo "$id,$based_on,$desc,$perf,$stat"
     fi
     ((current_row++))
-  done <evolution/evolution.csv >"$temp_file"
+  done <"$FULL_CSV_PATH" >"$temp_file"
 
-  mv "$temp_file" evolution/evolution.csv
+  mv "$temp_file" "$FULL_CSV_PATH"
 }
 
 # Find next candidate
@@ -126,9 +141,9 @@ trap 'update_csv_row "$row_num" "" "interrupted"; echo "[INFO] Evolution interru
 update_csv_row "$row_num" "" "running"
 
 # Determine parent algorithm
-parent_file="evolution/algorithm.py"
+parent_file="$FULL_ALGORITHM_PATH"
 if [[ -n $based_on_id && $based_on_id != "0" ]]; then
-  parent_file="evolution/evolution_id${based_on_id}.py"
+  parent_file="$FULL_OUTPUT_DIR/evolution_id${based_on_id}.py"
   if [[ ! -f $parent_file ]]; then
     echo "[ERROR] Parent algorithm file not found: $parent_file" >&2
     update_csv_row "$row_num" "" "failed"
@@ -139,7 +154,7 @@ fi
 echo "[INFO] Using parent algorithm: $parent_file"
 
 # Generate mutation
-output_file="evolution/evolution_id${id}.py"
+output_file="$FULL_OUTPUT_DIR/evolution_id${id}.py"
 echo "[INFO] Generating algorithm mutation..."
 
 # Copy parent algorithm to output file first
@@ -156,8 +171,8 @@ fi
 
 # Implement claude-fsd style model selection
 # Read/create loop counter for megathinking mode
-if [[ -f evolution/.loop_counter ]]; then
-  LOOP_COUNTER=$(cat evolution/.loop_counter)
+if [[ -f "$FULL_EVOLUTION_DIR/.loop_counter" ]]; then
+  LOOP_COUNTER=$(cat "$FULL_EVOLUTION_DIR/.loop_counter")
 else
   LOOP_COUNTER=1
 fi
@@ -175,13 +190,13 @@ else
 fi
 
 # Increment and save counter
-echo $((LOOP_COUNTER + 1)) > evolution/.loop_counter
+echo $((LOOP_COUNTER + 1)) > "$FULL_EVOLUTION_DIR/.loop_counter"
 
 # Create mutation prompt
 prompt="${MEGATHINK_PREFIX}You are an AI assistant helping to evolve algorithms through mutations. Please modify the Python algorithm file at $output_file based on the requested modification.
 
 CONTEXT:
-$(cat evolution/BRIEF.md 2>/dev/null || echo "No brief available")
+$(cat "$FULL_BRIEF_PATH" 2>/dev/null || echo "No brief available")
 
 ALGORITHM FILE TO MODIFY: $output_file
 
@@ -216,7 +231,7 @@ eval_exit_code=0
 
 if [[ -n $timeout_seconds ]]; then
   echo "[INFO] Starting evaluation with ${timeout_seconds}s timeout..."
-  if eval_output=$(timeout "$timeout_seconds" python3 evolution/evaluator.py "$output_file" 2>&1); then
+  if eval_output=$(timeout "$timeout_seconds" "$PYTHON_CMD" "$FULL_EVALUATOR_PATH" "$output_file" 2>&1); then
     eval_exit_code=0
   else
     eval_exit_code=$?
@@ -227,7 +242,7 @@ if [[ -n $timeout_seconds ]]; then
     fi
   fi
 else
-  if eval_output=$(python3 evolution/evaluator.py "$output_file" 2>&1); then
+  if eval_output=$("$PYTHON_CMD" "$FULL_EVALUATOR_PATH" "$output_file" 2>&1); then
     eval_exit_code=0
   else
     eval_exit_code=$?

package/package.json

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