claude-evolve
Evolutionary code discovery for Claude Code. No API keys, no cloud infrastructure, no extra services — just the claude CLI you already use.
claude-evolve is a native Claude Code plugin that reimplements the ShinkaEvolve algorithm (ICLR 2026) using Claude's built-in model tiers (opus, sonnet, haiku) at different thinking-effort levels as the LLM ensemble. It maintains populations of programs across islands, generates mutations via a UCB1 bandit over (model × effort) arms, and evolves code autonomously toward any fitness function you can evaluate with real code execution.
On the 26-circle packing benchmark from the ShinkaEvolve paper, claude-evolve reaches 99.94% of the reference state-of-the-art score (2.6343 vs 2.6360) in 50 generations with 3 islands — starting from a naive initial solution scoring 1.8378.
Table of Contents
What It Does
You give claude-evolve three things:
- An initial program with markers around the part you want to optimize
- An evaluator script that runs the program and returns a fitness score
- A config specifying the evolutionary budget
It runs an autonomous loop that:
- Asks Claude models to mutate your code (diff patches, full rewrites, crossover)
- Runs your evaluator on each mutation to measure fitness
- Keeps the best programs in an archive across multiple island populations
- Migrates elites between islands periodically
- Rejects near-duplicate proposals via AST-based novelty detection
- Uses a UCB1 bandit to learn which
(model × effort) combinations produce the biggest improvements
- Periodically generates meta-recommendations from top programs and injects them into future prompts
After N generations, the best program in the archive is your optimized solution.
Requirements
- Claude Code CLI (the
claude command) with an authenticated account
- Python 3.10 or newer on PATH
pip to install the claude-evolve Python package- Unix-like environment (Linux, macOS, WSL) — Windows native is not tested
- ~200 MB disk space for dependencies (numpy, scipy, aiosqlite, mcp)
You do not need:
- An Anthropic API key, OpenAI key, or any other external service credential
- A GPU
- Docker, SLURM, or other orchestration
- A network connection beyond what Claude Code already needs
Installation
Option 1: Claude Code plugin marketplace (recommended)
Run each command below in its own Claude Code message — do not paste them as a single block, since Claude Code interprets only the first slash command on a line.
1. Add the marketplace:
/plugin marketplace add https://github.com/samuelzxu/claude-evolve
2. Install the plugin:
/plugin install claude-evolve@evolve
3. Reload plugins so the new skills and MCP server register:
/reload-plugins
(Alternatively, restart Claude Code. Either way is required after any plugin install before its skills become callable in the current session.)
4. Run the setup skill to install Python dependencies and verify everything works:
/evolve-install
This will:
- Check your Python version (≥ 3.10 required)
- Create a venv in
core/.venv/ (or use system Python with --global)
- Install the
claude_evolve Python package in editable mode
- Verify the Claude CLI is available
- Confirm the MCP server exposes its five tools
- Run a smoke test that calls Claude once to verify the bridge
Option 2: Manual install from source
git clone https://github.com/samuelzxu/claude-evolve
cd claude-evolve
python3 -m venv core/.venv
source core/.venv/bin/activate
pip install -e core/
claude mcp add -s user claude-evolve -- python3 -m claude_evolve.server
Then open any Claude Code session and confirm the MCP server is connected:
claude mcp list
# Should show: claude-evolve: python3 -m claude_evolve.server - ✓ Connected
Quick Start (3 commands)
Once installed, there are two paths depending on what you already have.
Path A: You have a vague optimization goal
If you don't yet have initial.py and evaluate.py, run the guided interview:
/evolve-interview I want to improve the sorting algorithm in src/solver.py to minimize total wall-clock time on my benchmark dataset