EvolveX

Build agents that improve — and keep the evidence.

A file-based evolution framework for evaluator-driven learning, reproducible candidate lineage, and controllable modification.

What EvolveX Does · How It Works · What Can Evolve · Recipes · Showcase · Quick Start · Documentation

What EvolveX Does

EvolveX gives an agent a controlled way to improve itself. It runs candidates against a fixed evaluator, keeps the evidence for every generation, and carries verified improvements forward without letting candidate code rewrite the rules that score it.

• For agent builders: Improve prompts, skills, harnesses, and agent code in a reusable experiment workspace.
• For researchers: Compare evolution strategies under fixed evaluation and mutation boundaries.
• Evidence built in: Connect every candidate to scores, artifacts, archive records, and Git lineage.

How EvolveX Works

Every recipe composes the same loop:

select → evaluate → analyze → mutate → gate → record

A recipe decides how parents are selected, how traces are analyzed, what may be edited, and which evaluations admit a new generation. The framework owns the mechanism that makes those decisions inspectable: clean candidate snapshots, protected scoring, surface enforcement, Git tags, and stamped archive records.

What Can Evolve

Surface	Examples	Best fit
prompts and skills	system prompts, task skills, reusable instructions	policy and behavior improvement
harnesses and target code	tools, orchestration, agent implementation	agent engineering
selected evolution operators	analysis or mutation policy chosen by a recipe	controlled co-evolution

Each recipe declares its mutable paths. Evaluators, archive stamps, and the vendored framework mechanism stay outside that surface.

Recipes

Choose this when you want to…	Recipe	Mutable surface
improve one candidate from its current best parent	hill_climb	target
evolve prompts and reusable agent skills	aevolve	prompt and target skills
engineer the agent harness against evaluator feedback	ahe	target
balance multiple objectives with minibatch validation	gepa	prompt and task skill
co-evolve the target and selected evolution policy	hyperagents	target and selected operators

See the recipe guide for each strategy’s workflow and configuration.

Skill Evolution Showcase

EvolveX can improve a Skill as a complete package: instructions, references, and validation scripts evolve together while a frozen evaluator keeps the comparison honest. In this local Paper2Poster run, the same Codex model and paper prompt produced both LoRA posters below.

Gen 0 · minimal 12-line Skill	Gen 2 · evolved editorial Skill
Deterministic geometry gate failed: 14 text elements overflowed the SVG viewBox.	Passed deterministic renderability and geometry gates; paper fidelity remained advisory reviewer feedback.

Across the four-paper showcase, the deterministic completion pass rate moved from 1/4 at Gen 0 to 4/4 at Gen 2. The trials ran concurrently through Harbor's local environment without Docker and retained ATIF trajectories plus evaluator-owned visual feedback. This is a representative evolution run rather than a broad benchmark; see the result snapshot, frozen rubric, and minimal seed Skill.

Quick Start

Run one of the supported recipes against the shared, content-pinned Terminal-Bench 2.0 subset with ./scripts/setup_terminal_bench.sh and ./scripts/run_recipe_demo.sh. The quick start guide covers prerequisites, credential setup, supported recipe values, and launcher overrides.

Benchmark Results

Scores are solved-task counts shown as seed → best, with the absolute task-count change underneath. All runs use a GPT-5.4-high target model and a GPT-5.4-xhigh Codex meta-agent.

Terminal Bench 2

Split: 50 train / 19 gate / 20 sealed.

Target agent	Method	Train	Gate	Sealed
MiniSWE	AHE	35 → 37	13 → 13	16 → 14
	Hyperagents	29 → 34	13 → 14	16 → 14
	A-Evolve	33 → 34	11 → 15	14 → 13
	GEPA	29 → 34	11 → 13	14 → 15
Codex	AHE	30 → 37	10 → 9	13 → 14
	Hyperagents	29 → 36	10 → 11	13 → 15
	A-Evolve	29 → 36	9 → 13	14 → 12
	GEPA	30 → 30	12 → 12	16 → 16

Tau³ Banking

Split: 50 train / 20 gate / 27 sealed.

Target agent	Method	Train	Gate	Sealed
MiniSWE	AHE	17 → 18	9 → 7	7 → 7
	Hyperagents	15 → 19	9 → 9	7 → 10
	A-Evolve	15 → 17	7 → 9	5 → 8
	GEPA	15 → 16	8 → 9	5 → 7
Codex	AHE	16 → 18	9 → 9	5 → 4
	Hyperagents	17 → 18	9 → 10	5 → 13
	A-Evolve	15 → 19	6 → 9	2 → 5
	GEPA	17 → 18	6 → 7	2 → 4

Trustworthy by Construction

EvolveX separates evolvable policy from the mechanism that judges it:

1. The evaluator is frozen. Candidates cannot change the scoring contract.
2. Mutation is bounded. Each recipe declares which target and operator paths may change.
3. Evaluation is canonical. New generations are scored from clean candidate snapshots.
4. Evidence is durable. Reports recompute results from stamped archive.jsonl records and Git generation tags.

Operators run as subprocesses rather than being imported into the framework process. See the design guide for the complete ownership model and invariants.

Project Status

EvolveX is an active prototype for research and controlled experimentation. The current focus is reliable experiment mechanics, local-first workflows, and composable strategies for different agent-evolution scenarios.

Roadmap

• Scenario-oriented recipes: compose the current operator library into opinionated recipes for different agent-evolution use cases.
• Local-first workflows: make lightweight, Docker-free iteration a first-class path for trusted local agents, prompts, skills, and small features.
• More method integrations: add evolution and search methods while preserving the shared evaluator, lineage, and evidence contracts.

Documentation

Document	Purpose
Documentation site	Installation, operation, concepts, guides, and reference.
Quick start	Recipe launcher setup and configuration.
Design	System model, ownership boundaries, and invariants.
Architecture	Enforced source-module map and line budgets.
Recipes	Supported evolution strategies.
Evaluation assets	Skill behavior/routing evaluation cases and result snapshots.
Meta-agents	Trusted-host and isolated meta-agent runners.
Trace Analyzer	Trace retention and analyzer variants.
Local environment	Docker-free trusted local execution.
Operations	Doctor profiles, runtime setup, full-loop smoke, and recovery.
Contributing	Development setup and repository conventions.
Releasing	Source, artifact, and publication checklist.

License

EvolveX is licensed under Apache-2.0. See NOTICE for required attributions.