What is claude-evolve CLAUDE.md?

A set of Claude Code instructions for claude-evolve, a system that repeatedly improves code with Claude models and evaluates each version.

Use it to install the system, interview for an optimization task, start an evolution run, or check its progress.

It explains the project's setup and workflow so evolution tasks are defined and run consistently.

How samuelzxu/claude-evolve configures Claude Code

Reuse

Borrowing it

Nothing to install: this file belongs to samuelzxu/claude-evolve. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file

curl -O https://raw.githubusercontent.com/samuelzxu/claude-evolve/master/CLAUDE.md

Clone the repo

git clone --depth 1 https://github.com/samuelzxu/claude-evolve

Made for: Claude Code.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/samuelzxu/claude-evolve/claude-md.svg)](https://agentmods.dev/instructions/samuelzxu/claude-evolve/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/samuelzxu/claude-evolve/claude-md"><img src="https://agentmods.dev/badge/instructions/samuelzxu/claude-evolve/claude-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 818 This file is loaded in full into every session.

When invoked 818 The same file — it is already loaded in full.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00818	$0.00818
Opus 5	$0.00409	$0.00409
Sonnet 5	$0.00164	$0.00164
Haiku 4.5	$0.00082	$0.00082

Measured 5d ago against content hash 6aaec3e2a30b, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-07, from the pricing page.

Security

Grade A, and why

claude-evolve CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 5d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 63 lines

How it starts

The opening of the file, as written. The whole thing — 63 lines — stays where its author put it; the contents beside it link to each section on GitHub.

claude-evolve

Evolutionary code optimization using Claude Code models. Reimplements the ShinkaEvolve framework using Claude's built-in model access (opus/sonnet/haiku x effort levels) as the LLM ensemble -- no external API keys, no extra infrastructure.

Skills

/evolve-install — Install or verify the plugin (Python deps, venv, MCP server health check)
/evolve-interview — Socratic deep interview with mathematical ambiguity gating. Produces initial.py, evaluate.py, and config.json for any optimization task.
/evolve — Start an autonomous evolution run from existing spec files
/evolve-status — Check a running evolution's progress (generation, best score, bandit arm stats)

Quick Start

First time:

/evolve-install     # sets up Python env, verifies Claude CLI, registers MCP server
/evolve-interview   # guided interview to define your task -> writes spec files
/evolve             # launches the evolution run

Already have initial.py + evaluate.py:

/evolve             # just launches the run
/evolve-status      # check progress at any time

Anatomy of an Evolution Task

An evolution task needs three things:

initial.py — the seed program, with # EVOLVE-BLOCK-START / # EVOLVE-BLOCK-END markers around the code you want the LLM to mutate. Code outside those markers is preserved verbatim.
evaluate.py — a standalone evaluator script that runs the program and outputs a JSON dict with at minimum combined_score (float) and correct (bool). Fitness must come from real code execution, never LLM judgment.
config.json — an EvolveConfig JSON file specifying the bandit ensemble, island model, patch types, novelty threshold, and generation budget.

/evolve-interview generates all three through a Socratic dialogue. Use it when you don't have a clear spec yet.

How It Works

The plugin maintains populations of programs across islands. Each generation:

Select arm: UCB1 bandit picks a (model, effort) pair from the ensemble (e.g. haiku/high, sonnet/medium)
Select parent: weighted or power-law sampling from an island population
Build prompt: includes parent code, inspirations from the archive, and a randomly-chosen persona (replaces temperature diversity)
Query Claude: subprocess call to claude --model X --effort Y -p <prompt> with large output token budget
Apply patch: diff (SEARCH/REPLACE), full rewrite, crossover, or fix (for broken mutations)
Check novelty: AST fingerprint + MinHash similarity rejects near-duplicate proposals
Evaluate: run python3 evaluate.py --program_path <candidate> as subprocess, parse JSON
Update database: store the program, update bandit reward based on improvement over parent
Periodic: meta-scratchpad recommendations, prompt co-evolution, island migration

Read the full file on GitHub · 63 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

5d ago First seen · 63 lines · 818 tokens per session scan A 6aaec3e2a30b

Subscribe to this mod's changes

claude-evolve CLAUDE.md is an instructions file published in the GitHub repository samuelzxu/claude-evolve (16 stars, last pushed 2mo ago), licensed MIT. It adds 818 tokens to every session, about $0.0041 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-01.

Building agents Planning

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,182 tokens

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

claude-evolve: Instructions file for Claude Code