claude-evolve 1.3.40 → 1.3.41
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -354
- package/bin/claude-evolve-main +16 -14
- package/bin/claude-evolve-run +5 -5
- package/bin/claude-evolve-worker +10 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,403 +1,128 @@
|
|
|
1
1
|
# claude-evolve
|
|
2
2
|
|
|
3
|
-
Automated algorithm evolution
|
|
3
|
+
Automated algorithm evolution using AI. Start with a base algorithm, let Claude evolve better variants autonomously.
|
|
4
4
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
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.
|
|
8
|
-
|
|
9
|
-
Think of it like **genetic algorithms for code** - it handles the mutations and testing, and runs **indefinitely** until you stop it. The system automatically generates new ideas when it runs out of candidates.
|
|
10
|
-
|
|
11
|
-

|
|
12
|
-
|
|
13
|
-
### How the Evolution System Works
|
|
14
|
-
|
|
15
|
-
The system operates with specialized phases working together:
|
|
16
|
-
|
|
17
|
-
- 🧠 **Ideation Phase**: Generates creative algorithm variations using codex o3-pro (if available) or Claude Opus
|
|
18
|
-
- 🔬 **Development Phase**: Implements mutations using Claude Sonnet (with periodic Opus "megathinking")
|
|
19
|
-
- 📊 **Evaluation Phase**: Tests performance against your custom evaluator
|
|
20
|
-
- 📈 **Analysis Phase**: Tracks evolution progress and identifies top performers
|
|
21
|
-
|
|
22
|
-
The evolution cycle:
|
|
23
|
-
```
|
|
24
|
-
Ideate → Mutate → Evaluate → (Auto-Generate New Ideas) → Repeat Forever
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
**Truly autonomous evolution**: The system runs indefinitely, automatically generating new generations of ideas when it exhausts current candidates. You can leave it running overnight, over the weekend, or while you work on other things - it just keeps evolving better algorithms until you manually stop it with Ctrl+C.
|
|
28
|
-
|
|
29
|
-
## Installation
|
|
5
|
+
## Install & Quick Start
|
|
30
6
|
|
|
31
7
|
```bash
|
|
8
|
+
# Install
|
|
32
9
|
npm install -g claude-evolve
|
|
33
|
-
```
|
|
34
10
|
|
|
35
|
-
|
|
11
|
+
# Set up project
|
|
12
|
+
claude-evolve setup
|
|
36
13
|
|
|
37
|
-
|
|
38
|
-
claude-evolve
|
|
14
|
+
# Generate initial ideas
|
|
15
|
+
claude-evolve ideate
|
|
16
|
+
|
|
17
|
+
# Start evolution (runs forever until Ctrl+C)
|
|
18
|
+
claude-evolve run
|
|
39
19
|
```
|
|
40
20
|
|
|
41
|
-
|
|
21
|
+
## How It Works
|
|
22
|
+
|
|
23
|
+
1. **Write your problem** in `evolution/BRIEF.md`
|
|
24
|
+
2. **Create base algorithm** in `evolution/algorithm.py`
|
|
25
|
+
3. **Define evaluation** in `evolution/evaluator.py`
|
|
26
|
+
4. **Generate ideas** - Claude creates algorithm variations
|
|
27
|
+
5. **Evolve automatically** - System tests variations, keeps best ones, generates new ideas
|
|
42
28
|
|
|
43
|
-
|
|
44
|
-
2. **Write evolution/BRIEF.md** - Describe your optimization problem
|
|
45
|
-
3. **Customize evolution/evaluator.py** - Define how to measure algorithm performance
|
|
46
|
-
4. **Generate ideas** - Create initial algorithm candidates
|
|
47
|
-
5. **Start evolution** - Begin the automated evolution process
|
|
29
|
+
Evolution runs indefinitely until you stop it. Perfect for overnight optimization.
|
|
48
30
|
|
|
49
31
|
## Commands
|
|
50
32
|
|
|
51
|
-
### Main wrapper command
|
|
52
33
|
```bash
|
|
53
|
-
claude-evolve
|
|
54
|
-
claude-evolve setup
|
|
55
|
-
claude-evolve ideate
|
|
56
|
-
claude-evolve run
|
|
57
|
-
claude-evolve analyze
|
|
58
|
-
claude-evolve
|
|
59
|
-
claude-evolve
|
|
34
|
+
claude-evolve # Interactive menu
|
|
35
|
+
claude-evolve setup # Initialize workspace
|
|
36
|
+
claude-evolve ideate # Generate new algorithm ideas
|
|
37
|
+
claude-evolve run # Start evolution loop (runs forever)
|
|
38
|
+
claude-evolve analyze # View results and progress
|
|
39
|
+
claude-evolve status # Quick progress overview
|
|
40
|
+
claude-evolve edit # Manage candidate statuses
|
|
60
41
|
```
|
|
61
42
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
#### claude-evolve-setup
|
|
65
|
-
Initializes your evolution workspace with:
|
|
66
|
-
- Directory structure
|
|
67
|
-
- Template files (BRIEF.md, algorithm.py, evaluator.py, config.yaml)
|
|
68
|
-
- CSV file for tracking evolution progress
|
|
69
|
-
|
|
70
|
-
#### claude-evolve-ideate
|
|
71
|
-
Generates new algorithm variation ideas using multi-strategy evolutionary approach:
|
|
72
|
-
- **Novel exploration** - Pure creativity for global search
|
|
73
|
-
- **Hill climbing** - Parameter tuning of top performers
|
|
74
|
-
- **Structural mutation** - Algorithmic changes to successful designs
|
|
75
|
-
- **Crossover hybrid** - Combines successful approaches
|
|
76
|
-
- Uses Claude Opus in megathinking mode for each strategy
|
|
77
|
-
- Configurable strategy distribution (default: 3+5+3+4 = 15 ideas)
|
|
78
|
-
|
|
79
|
-
#### claude-evolve-run
|
|
80
|
-
Executes evolution candidates in an **infinite loop**:
|
|
81
|
-
- Picks the next untested idea from your CSV
|
|
82
|
-
- Uses Claude to implement the mutation
|
|
83
|
-
- Runs your evaluator to measure performance
|
|
84
|
-
- Records results and updates the evolution log
|
|
85
|
-
- **When no candidates remain**: Automatically generates new ideas and continues
|
|
86
|
-
- **Runs forever until manually stopped** (Ctrl+C)
|
|
87
|
-
|
|
88
|
-
#### claude-evolve-analyze
|
|
89
|
-
Analyzes evolution progress and generates insights:
|
|
90
|
-
- Performance trends over time
|
|
91
|
-
- Best-performing algorithm variants
|
|
92
|
-
- Suggestions for future evolution directions
|
|
93
|
-
|
|
94
|
-
#### claude-evolve-edit
|
|
95
|
-
Manages candidate statuses by generation for re-evaluation workflows:
|
|
96
|
-
- Mark generations as failed, complete, or pending
|
|
97
|
-
- Reset entire generations (delete files and clear scores)
|
|
98
|
-
- Essential for re-running evaluations when algorithms or evaluators change
|
|
43
|
+
## Working with Multiple Projects
|
|
99
44
|
|
|
100
45
|
```bash
|
|
101
|
-
|
|
102
|
-
claude-evolve
|
|
103
|
-
claude-evolve
|
|
46
|
+
# Use different working directory
|
|
47
|
+
claude-evolve --working-dir=my-project run
|
|
48
|
+
claude-evolve --working-dir=experiments/trading ideate
|
|
104
49
|
```
|
|
105
50
|
|
|
106
|
-
#### claude-evolve-config
|
|
107
|
-
Manages configuration settings:
|
|
108
|
-
- View current configuration
|
|
109
|
-
- Edit paths and behavior settings
|
|
110
|
-
- Reset to defaults
|
|
111
|
-
|
|
112
|
-
## How it Works
|
|
113
|
-
|
|
114
|
-
1. **Set up evolution workspace** - Define your optimization problem
|
|
115
|
-
2. **Create base algorithm** - Start with `evolution/algorithm.py`
|
|
116
|
-
3. **Define evaluation criteria** - Customize `evolution/evaluator.py`
|
|
117
|
-
4. **Generate initial ideas** - Run `claude-evolve ideate` to create variations
|
|
118
|
-
5. **Start evolution loop** - The system automatically:
|
|
119
|
-
- Picks the next candidate from your CSV
|
|
120
|
-
- Implements the mutation
|
|
121
|
-
- Evaluates performance
|
|
122
|
-
- Records results
|
|
123
|
-
- **Generates new ideas when candidates are exhausted**
|
|
124
|
-
- **Repeats forever until manually stopped**
|
|
125
|
-
|
|
126
|
-
## Monitoring Progress (Like Genetic Algorithms)
|
|
127
|
-
|
|
128
|
-
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.
|
|
129
|
-
|
|
130
|
-
**Recommended monitoring approach:**
|
|
131
|
-
- **Check evolution.csv** - Track performance of all variants
|
|
132
|
-
- **Review top performers** - Look at the best algorithms generated so far
|
|
133
|
-
- **Monitor for convergence** - Watch for diminishing returns or local optima
|
|
134
|
-
- **Inject new ideas** - Add manual variations when evolution stagnates
|
|
135
|
-
|
|
136
|
-
**When you need to guide evolution:**
|
|
137
|
-
- **Add targeted ideas** - Use `claude-evolve ideate` with specific directions
|
|
138
|
-
- **Modify the evaluator** - Update `evolution/evaluator.py` to change selection pressure
|
|
139
|
-
- **Restart from best** - Copy top performer to `algorithm.py` and continue evolving
|
|
140
|
-
- **The system adapts** - New ideas will build on your guidance
|
|
141
|
-
|
|
142
|
-
**Infinite evolution with manual control:**
|
|
143
|
-
- **Runs forever** - automatically generates new generations of ideas
|
|
144
|
-
- **Hit Ctrl+C anytime** to stop the evolution process
|
|
145
|
-
- **Restart later** with `claude-evolve run` to continue from where you left off
|
|
146
|
-
- **Perfect for long-term optimization** - run overnight, over weekends, or while working on other projects
|
|
147
|
-
|
|
148
|
-
## Handling Failures and Recovery
|
|
149
|
-
|
|
150
|
-
Evolution experiments can fail for various reasons. The system tracks these failures and provides recovery options.
|
|
151
|
-
|
|
152
|
-
**Common failure types:**
|
|
153
|
-
- **Infrastructure failures** - Missing dependencies (e.g., xgboost not installed)
|
|
154
|
-
- **Code generation bugs** - Claude occasionally generates syntactically incorrect code
|
|
155
|
-
- **Evaluation errors** - Evaluator crashes or returns invalid output
|
|
156
|
-
- **Performance score 0** - Algorithm runs but produces no meaningful results (now marked as "failed")
|
|
157
|
-
|
|
158
|
-
**Failure tracking in evolution.csv:**
|
|
159
|
-
- `failed` - Evaluation error or performance score of 0
|
|
160
|
-
- `timeout` - Evaluation exceeded time limit
|
|
161
|
-
- `interrupted` - User interrupted with Ctrl+C
|
|
162
|
-
- Check the `status` column to identify failed candidates
|
|
163
|
-
|
|
164
|
-
**Manual recovery strategies:**
|
|
165
|
-
1. **Force retry of failed candidates:**
|
|
166
|
-
- Edit `evolution.csv` and change status from "failed" to "pending"
|
|
167
|
-
- Clear the performance value for that row
|
|
168
|
-
- Run `claude-evolve run` to retry the candidate
|
|
169
|
-
|
|
170
|
-
2. **Fix infrastructure issues:**
|
|
171
|
-
- Install missing dependencies: `pip install xgboost numpy scipy`
|
|
172
|
-
- Update Python environment if needed
|
|
173
|
-
- Check that evaluator.py has proper error handling
|
|
174
|
-
|
|
175
|
-
3. **Guide around persistent failures:**
|
|
176
|
-
- If a specific approach keeps failing, add constraints to BRIEF.md
|
|
177
|
-
- Use `claude-evolve ideate` with explicit directions to avoid problematic patterns
|
|
178
|
-
- Consider updating evaluator.py to catch and handle specific error types
|
|
179
|
-
|
|
180
|
-
**Future auto-recovery (planned):**
|
|
181
|
-
- Automatic retry with different prompts for code generation failures
|
|
182
|
-
- Dependency detection and installation suggestions
|
|
183
|
-
- Smart failure pattern recognition to avoid similar mutations
|
|
184
|
-
|
|
185
|
-
## Requirements
|
|
186
|
-
|
|
187
|
-
### Required
|
|
188
|
-
- Node.js >= 14.0.0
|
|
189
|
-
- Python 3.x (for algorithm execution)
|
|
190
|
-
- Automatically detected on all platforms
|
|
191
|
-
- Windows: Uses `python` if it's Python 3
|
|
192
|
-
- macOS/Linux: Prefers `python3`
|
|
193
|
-
- Can override in config.yaml: `python_cmd: "C:\\Python39\\python.exe"`
|
|
194
|
-
- Bash shell (Git Bash on Windows, native on macOS/Linux)
|
|
195
|
-
- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` command)
|
|
196
|
-
|
|
197
|
-
### Optional (but recommended)
|
|
198
|
-
- [Codex CLI](https://github.com/aboutgaurav/codex) (`codex` command) - Uses o3-pro model for superior ideation when available
|
|
199
|
-
- Scientific Python libraries (numpy, scipy, etc.) depending on your algorithms
|
|
200
|
-
- Plotting libraries (matplotlib, plotly) for analyzing results
|
|
201
|
-
|
|
202
51
|
## Project Structure
|
|
203
52
|
|
|
204
|
-
Your evolution workspace will have:
|
|
205
53
|
```
|
|
206
54
|
your-project/
|
|
207
55
|
├── evolution/
|
|
208
|
-
│ ├── BRIEF.md # Problem description
|
|
209
|
-
│ ├── algorithm.py # Base algorithm
|
|
210
|
-
│ ├── evaluator.py # Performance
|
|
211
|
-
│ ├── config.yaml #
|
|
212
|
-
│ ├── evolution.csv #
|
|
213
|
-
│
|
|
214
|
-
│ ├── evolution_id2.py
|
|
215
|
-
│ └── ...
|
|
216
|
-
└── (your main project files)
|
|
56
|
+
│ ├── BRIEF.md # Problem description
|
|
57
|
+
│ ├── algorithm.py # Base algorithm
|
|
58
|
+
│ ├── evaluator.py # Performance measurement
|
|
59
|
+
│ ├── config.yaml # Settings
|
|
60
|
+
│ ├── evolution.csv # Progress tracking
|
|
61
|
+
│ └── evolution_*.py # Generated variants
|
|
217
62
|
```
|
|
218
63
|
|
|
219
|
-
##
|
|
220
|
-
|
|
221
|
-
The evolution.csv file tracks all candidates and their results. The core columns are:
|
|
222
|
-
|
|
223
|
-
**Required columns (positions 1-5):**
|
|
224
|
-
1. **id** - Unique identifier for each candidate (e.g., gen01-001, gen02-015)
|
|
225
|
-
2. **basedOnId** - Parent algorithm this was derived from (empty for novel ideas)
|
|
226
|
-
3. **description** - What changes this variant implements
|
|
227
|
-
4. **performance** - Score from evaluator (column 4) - this drives evolution selection
|
|
228
|
-
5. **status** - Current state: empty/"pending", "running", "complete", "failed", "timeout"
|
|
229
|
-
|
|
230
|
-
**Additional columns:**
|
|
231
|
-
- Any other metrics your evaluator outputs (fitness, sharpe, total_return, yearly_return, max_drawdown, volatility, etc.)
|
|
232
|
-
- Error messages for failed runs
|
|
233
|
-
- Execution time
|
|
234
|
-
|
|
235
|
-
**Key behaviors:**
|
|
236
|
-
- The system uses column 4 (performance) for evolution selection, regardless of its name
|
|
237
|
-
- Column 5 (status) determines what needs to be run
|
|
238
|
-
- Empty or "pending" status means the candidate is ready to run
|
|
239
|
-
- You can reset a candidate to pending by deleting all fields after the description (columns 4+)
|
|
240
|
-
- Additional columns are automatically added when your evaluator returns JSON with extra fields
|
|
241
|
-
- Rows with fewer than 5 fields are treated as pending candidates
|
|
242
|
-
|
|
243
|
-
## Evaluator Output Format
|
|
64
|
+
## Evaluator Requirements
|
|
244
65
|
|
|
245
|
-
Your evaluator must output a performance score to stdout
|
|
66
|
+
Your `evaluator.py` must output a performance score to stdout:
|
|
246
67
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
1.077506371224117
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
### 2. JSON with "score" field
|
|
254
|
-
```json
|
|
255
|
-
{"score": 0.95}
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### 3. JSON with "performance" field
|
|
259
|
-
```json
|
|
260
|
-
{"performance": 1.234}
|
|
261
|
-
```
|
|
68
|
+
```python
|
|
69
|
+
# Simple: just print a number
|
|
70
|
+
print(1.234)
|
|
262
71
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
```json
|
|
266
|
-
{
|
|
267
|
-
"performance": 0.95,
|
|
268
|
-
"fitness": 0.82,
|
|
269
|
-
"sharpe_ratio": 1.23,
|
|
270
|
-
"max_drawdown": -0.15,
|
|
271
|
-
"total_return": 0.42,
|
|
272
|
-
"win_rate": 0.65
|
|
273
|
-
}
|
|
72
|
+
# Advanced: JSON with metrics
|
|
73
|
+
print('{"performance": 1.234, "accuracy": 0.95}')
|
|
274
74
|
```
|
|
275
75
|
|
|
276
|
-
|
|
277
|
-
- The system accepts either `performance` or `score` (they are treated the same)
|
|
278
|
-
- Higher scores indicate better performance
|
|
279
|
-
- A score of 0 indicates complete failure and marks the candidate as "failed"
|
|
280
|
-
- Non-zero exit codes indicate evaluation errors
|
|
281
|
-
- Any additional output (warnings, logs) should go to stderr, not stdout
|
|
282
|
-
- Additional JSON fields will be automatically added as new CSV columns
|
|
283
|
-
- New columns are added after the standard columns (id, basedOnId, description, performance, status)
|
|
284
|
-
- Common additional fields include: fitness, sharpe, sortino, total_return, yearly_return, max_drawdown, volatility, total_trades, win_rate, profit_factor, final_value
|
|
285
|
-
|
|
286
|
-
## Environment Variables for Evaluators
|
|
287
|
-
|
|
288
|
-
When your evaluator.py runs, it has access to the `EXPERIMENT_ID` environment variable containing the current experiment's ID (e.g., `gen07-001`). This allows evaluators to:
|
|
76
|
+
Higher scores = better performance. Score of 0 = failure.
|
|
289
77
|
|
|
290
|
-
|
|
291
|
-
- Log metrics with experiment identifiers
|
|
292
|
-
- Implement experiment-aware logic
|
|
293
|
-
- Track which algorithm variant is being evaluated
|
|
294
|
-
|
|
295
|
-
Example usage in evaluator.py:
|
|
296
|
-
```python
|
|
297
|
-
import os
|
|
78
|
+
## Configuration
|
|
298
79
|
|
|
299
|
-
|
|
300
|
-
experiment_id = os.environ.get('EXPERIMENT_ID', 'unknown')
|
|
80
|
+
Edit `evolution/config.yaml`:
|
|
301
81
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
82
|
+
```yaml
|
|
83
|
+
# Files
|
|
84
|
+
algorithm_file: "algorithm.py"
|
|
85
|
+
evaluator_file: "evaluator.py"
|
|
86
|
+
evolution_csv: "evolution.csv"
|
|
305
87
|
|
|
306
|
-
#
|
|
307
|
-
|
|
88
|
+
# Evolution strategy
|
|
89
|
+
ideation_strategies:
|
|
90
|
+
total_ideas: 15
|
|
91
|
+
novel_exploration: 3 # Creative new approaches
|
|
92
|
+
hill_climbing: 5 # Parameter tuning
|
|
93
|
+
structural_mutation: 3 # Architecture changes
|
|
94
|
+
crossover_hybrid: 4 # Combine best features
|
|
95
|
+
|
|
96
|
+
# Auto-generate new ideas when queue empty
|
|
97
|
+
auto_ideate: true
|
|
98
|
+
|
|
99
|
+
# Parallel execution
|
|
100
|
+
parallel:
|
|
101
|
+
enabled: false
|
|
102
|
+
max_workers: 4
|
|
308
103
|
```
|
|
309
104
|
|
|
310
|
-
##
|
|
105
|
+
## Requirements
|
|
311
106
|
|
|
312
|
-
|
|
107
|
+
- Node.js 14+
|
|
108
|
+
- Python 3.x
|
|
109
|
+
- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)
|
|
110
|
+
- Bash shell (Git Bash on Windows)
|
|
313
111
|
|
|
314
|
-
|
|
315
|
-
# NOTE: The evolution directory is automatically inferred from this config file's location.
|
|
316
|
-
# For example, if this file is at /path/to/my-experiment/config.yaml,
|
|
317
|
-
# then the evolution directory will be /path/to/my-experiment/
|
|
112
|
+
## Tips
|
|
318
113
|
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
114
|
+
- **Start simple** - Basic algorithm, let evolution add complexity
|
|
115
|
+
- **Monitor progress** - Check `evolution.csv` for performance trends
|
|
116
|
+
- **Guide evolution** - Add manual ideas when stuck in local optima
|
|
117
|
+
- **Let it run** - Evolution works best over long periods
|
|
323
118
|
|
|
324
|
-
|
|
325
|
-
evolution_csv: "evolution.csv"
|
|
119
|
+
## Common Issues
|
|
326
120
|
|
|
327
|
-
|
|
328
|
-
parent_selection: "best" # or "random", "latest"
|
|
121
|
+
**Too many failures?** Check your evaluator handles edge cases and outputs valid scores.
|
|
329
122
|
|
|
330
|
-
|
|
331
|
-
ideation_strategies:
|
|
332
|
-
total_ideas: 15 # Total ideas per generation
|
|
333
|
-
novel_exploration: 3 # Pure creativity, global search
|
|
334
|
-
hill_climbing: 5 # Parameter tuning of top performers
|
|
335
|
-
structural_mutation: 3 # Algorithmic changes to top performers
|
|
336
|
-
crossover_hybrid: 4 # Combine successful approaches
|
|
337
|
-
num_elites: 3 # Number of top performers to use as parents
|
|
338
|
-
|
|
339
|
-
# Python command to use for evaluation
|
|
340
|
-
python_cmd: "python3"
|
|
341
|
-
```
|
|
123
|
+
**Stuck in local optimum?** Increase `novel_exploration` in config.yaml or add manual ideas.
|
|
342
124
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
The ideation system uses evolutionary algorithm principles with four complementary strategies:
|
|
346
|
-
|
|
347
|
-
**🎯 Novel Exploration (Global Search)**
|
|
348
|
-
- Generates completely new algorithmic approaches
|
|
349
|
-
- Prevents getting stuck in local optima
|
|
350
|
-
- Explores different paradigms, data structures, mathematical approaches
|
|
351
|
-
- Essential for breakthrough innovations
|
|
352
|
-
|
|
353
|
-
**⛰️ Hill Climbing (Exploitation)**
|
|
354
|
-
- Fine-tunes parameters of successful algorithms
|
|
355
|
-
- Adjusts constants, thresholds, iteration counts
|
|
356
|
-
- Quick wins through incremental improvements
|
|
357
|
-
- Builds on proven approaches
|
|
358
|
-
|
|
359
|
-
**🔧 Structural Mutation (Medium-Distance Search)**
|
|
360
|
-
- Redesigns implementation while keeping core insights
|
|
361
|
-
- Changes data structures, sub-algorithms, execution patterns
|
|
362
|
-
- Balances innovation with proven concepts
|
|
363
|
-
- Explores architectural variations
|
|
364
|
-
|
|
365
|
-
**🧬 Crossover Hybrid (Recombination)**
|
|
366
|
-
- Combines successful elements from different top performers
|
|
367
|
-
- Creates novel interactions between proven approaches
|
|
368
|
-
- Leverages diversity in the population
|
|
369
|
-
- Often produces unexpected breakthrough combinations
|
|
370
|
-
|
|
371
|
-
**⚖️ Strategy Balance**
|
|
372
|
-
The default 3+5+3+4 distribution provides:
|
|
373
|
-
- 20% wild exploration (escape local maxima)
|
|
374
|
-
- 33% focused exploitation (quick improvements)
|
|
375
|
-
- 20% structural innovation (medium jumps)
|
|
376
|
-
- 27% recombination (leverage diversity)
|
|
377
|
-
|
|
378
|
-
**🎛️ Tuning Your Evolution**
|
|
379
|
-
Adjust ratios based on your needs:
|
|
380
|
-
- **Stuck in local optimum?** Increase `novel_exploration` and `structural_mutation`
|
|
381
|
-
- **Need incremental gains?** Increase `hill_climbing`
|
|
382
|
-
- **Population too similar?** Increase `crossover_hybrid`
|
|
383
|
-
- **Want faster convergence?** Decrease `total_ideas`, increase `hill_climbing`
|
|
384
|
-
|
|
385
|
-
## Tips for Success
|
|
386
|
-
|
|
387
|
-
1. **Write a clear BRIEF.md** - Describe your optimization problem, constraints, and goals
|
|
388
|
-
2. **Create a robust evaluator** - Your evaluator.py determines evolution direction
|
|
389
|
-
3. **Start simple** - Begin with a basic algorithm and let evolution add complexity
|
|
390
|
-
4. **Monitor early cycles** - Watch the first few evolutions to ensure proper setup
|
|
391
|
-
5. **Guide when stuck** - Add manual ideas when evolution hits local optima
|
|
392
|
-
6. **Embrace failures** - Not every mutation will be better, that's how evolution works
|
|
393
|
-
|
|
394
|
-
## Example Use Cases
|
|
395
|
-
|
|
396
|
-
- **Algorithm optimization** - Improve sorting, searching, or mathematical algorithms
|
|
397
|
-
- **Machine learning** - Evolve model architectures or training procedures
|
|
398
|
-
- **Game AI** - Develop and optimize game-playing strategies
|
|
399
|
-
- **Numerical methods** - Improve solvers, optimizers, or approximation algorithms
|
|
400
|
-
- **Data structures** - Evolve efficient data organization strategies
|
|
125
|
+
**Evaluator crashes?** Make sure dependencies are installed and error handling is robust.
|
|
401
126
|
|
|
402
127
|
## License
|
|
403
128
|
|
package/bin/claude-evolve-main
CHANGED
|
@@ -55,7 +55,7 @@ show_help() {
|
|
|
55
55
|
claude-evolve - AI-powered algorithm evolution tool
|
|
56
56
|
|
|
57
57
|
USAGE:
|
|
58
|
-
claude-evolve [--
|
|
58
|
+
claude-evolve [--working-dir=PATH] [COMMAND] [OPTIONS]
|
|
59
59
|
|
|
60
60
|
COMMANDS:
|
|
61
61
|
setup Initialize evolution workspace
|
|
@@ -69,16 +69,16 @@ COMMANDS:
|
|
|
69
69
|
help Show this help message
|
|
70
70
|
|
|
71
71
|
GLOBAL OPTIONS:
|
|
72
|
-
--
|
|
73
|
-
-h, --help
|
|
74
|
-
-v, --version
|
|
72
|
+
--working-dir=PATH Use alternate working directory (default: evolution/)
|
|
73
|
+
-h, --help Show help message
|
|
74
|
+
-v, --version Show version
|
|
75
75
|
|
|
76
76
|
EXAMPLES:
|
|
77
77
|
claude-evolve setup
|
|
78
78
|
claude-evolve ideate 5
|
|
79
79
|
claude-evolve run --timeout 300
|
|
80
80
|
claude-evolve analyze --open
|
|
81
|
-
claude-evolve --
|
|
81
|
+
claude-evolve --working-dir=evolution-abc run
|
|
82
82
|
|
|
83
83
|
For more information, visit: https://github.com/anthropics/claude-evolve
|
|
84
84
|
EOF
|
|
@@ -111,19 +111,19 @@ show_menu() {
|
|
|
111
111
|
}
|
|
112
112
|
|
|
113
113
|
# Parse global options
|
|
114
|
-
|
|
114
|
+
WORKING_DIR=""
|
|
115
115
|
while [[ $# -gt 0 ]] && [[ "$1" =~ ^-- ]]; do
|
|
116
116
|
case "$1" in
|
|
117
|
-
--
|
|
117
|
+
--working-dir)
|
|
118
118
|
if [[ -z ${2:-} ]]; then
|
|
119
|
-
echo -e "${RED}[ERROR] --
|
|
119
|
+
echo -e "${RED}[ERROR] --working-dir requires a directory path${NC}" >&2
|
|
120
120
|
exit 1
|
|
121
121
|
fi
|
|
122
|
-
|
|
122
|
+
WORKING_DIR="$2"
|
|
123
123
|
shift 2
|
|
124
124
|
;;
|
|
125
|
-
--
|
|
126
|
-
|
|
125
|
+
--working-dir=*)
|
|
126
|
+
WORKING_DIR="${1#*=}"
|
|
127
127
|
shift
|
|
128
128
|
;;
|
|
129
129
|
*)
|
|
@@ -132,9 +132,11 @@ while [[ $# -gt 0 ]] && [[ "$1" =~ ^-- ]]; do
|
|
|
132
132
|
esac
|
|
133
133
|
done
|
|
134
134
|
|
|
135
|
-
# Export
|
|
136
|
-
if [[ -n $
|
|
137
|
-
|
|
135
|
+
# Export config file path for subcommands
|
|
136
|
+
if [[ -n $WORKING_DIR ]]; then
|
|
137
|
+
# Remove trailing slash if present
|
|
138
|
+
WORKING_DIR="${WORKING_DIR%/}"
|
|
139
|
+
export CLAUDE_EVOLVE_CONFIG="$WORKING_DIR/config.yaml"
|
|
138
140
|
fi
|
|
139
141
|
|
|
140
142
|
# Check for updates (quick, non-blocking)
|
package/bin/claude-evolve-run
CHANGED
|
@@ -249,11 +249,11 @@ cleanup_workers() {
|
|
|
249
249
|
# Check if we've hit the failure limit
|
|
250
250
|
if [[ $consecutive_failures -ge $MAX_CONSECUTIVE_FAILURES ]]; then
|
|
251
251
|
echo "" >&2
|
|
252
|
-
echo "
|
|
253
|
-
echo "
|
|
254
|
-
echo "
|
|
255
|
-
echo "
|
|
256
|
-
echo "
|
|
252
|
+
echo "⚠️ EVOLUTION PAUSED: Multiple consecutive failures detected" >&2
|
|
253
|
+
echo "⚠️ $consecutive_failures consecutive worker failures - indicates systemic issues" >&2
|
|
254
|
+
echo "⚠️ Possible causes: Claude API issues, evaluator bugs, configuration problems" >&2
|
|
255
|
+
echo "⚠️ Check recent worker logs in logs/ directory for specific error details" >&2
|
|
256
|
+
echo "⚠️ Fix issues before restarting evolution" >&2
|
|
257
257
|
echo "" >&2
|
|
258
258
|
|
|
259
259
|
# Shutdown all workers and exit
|
package/bin/claude-evolve-worker
CHANGED
|
@@ -213,7 +213,9 @@ The file currently contains the parent algorithm. Modify it according to the des
|
|
|
213
213
|
|
|
214
214
|
# Check for rate limit (multiple possible messages)
|
|
215
215
|
if echo "$claude_output" | grep -q -E "(usage limit|rate limit|limit reached|too many requests)"; then
|
|
216
|
-
echo "
|
|
216
|
+
echo "⚠️ Claude API rate limit reached" >&2
|
|
217
|
+
echo "⚠️ Claude output:" >&2
|
|
218
|
+
echo "$claude_output" >&2
|
|
217
219
|
# Clean up the temp file
|
|
218
220
|
if [[ -f "$temp_file" ]]; then
|
|
219
221
|
rm "$temp_file"
|
|
@@ -225,7 +227,9 @@ The file currently contains the parent algorithm. Modify it according to the des
|
|
|
225
227
|
fi
|
|
226
228
|
|
|
227
229
|
if [[ $claude_exit_code -ne 0 ]]; then
|
|
228
|
-
echo "
|
|
230
|
+
echo "⚠️ Claude failed to mutate algorithm (exit code: $claude_exit_code)" >&2
|
|
231
|
+
echo "⚠️ Claude output:" >&2
|
|
232
|
+
echo "$claude_output" >&2
|
|
229
233
|
# Clean up the temp file
|
|
230
234
|
if [[ -f "$temp_file" ]]; then
|
|
231
235
|
rm "$temp_file"
|
|
@@ -238,13 +242,10 @@ The file currently contains the parent algorithm. Modify it according to the des
|
|
|
238
242
|
# Verify that Claude actually modified the file
|
|
239
243
|
if [[ -f "$temp_file" && -f "$parent_file" ]]; then
|
|
240
244
|
if cmp -s "$temp_file" "$parent_file"; then
|
|
241
|
-
echo "" >&2
|
|
242
|
-
echo "
|
|
243
|
-
echo "
|
|
244
|
-
echo "
|
|
245
|
-
echo "ERROR: Marking as failed - no evaluation will run" >&2
|
|
246
|
-
echo "🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨" >&2
|
|
247
|
-
echo "" >&2
|
|
245
|
+
echo "⚠️ Unchanged algorithm detected - Claude didn't modify the file" >&2
|
|
246
|
+
echo "⚠️ Description was: $description" >&2
|
|
247
|
+
echo "⚠️ Claude's response:" >&2
|
|
248
|
+
echo "$claude_output" >&2
|
|
248
249
|
|
|
249
250
|
# Clean up temp file and mark as failed
|
|
250
251
|
rm "$temp_file"
|