autoevolve
OfficialAllows autoevolve to manage GitHub issues and pull requests, including commenting on contract proposals, applying approval labels, and creating PRs with winning code and reports for issue-driven evolution runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@autoevolve make the image pipeline at least 10x faster"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
autoevolve
Agent-native evolutionary optimization. You state a goal in english. The system synthesizes a scoring contract, measures the baseline, checks feasibility, then evolves code toward the target with a parallel population of coding-agent workers, and ships the result as a report or a PR.
The promise on every run: hit the target, or deliver best-found plus an evidence-backed explanation of the ceiling. Both are successful outcomes.
What a run looks like

The goal above was "make the image pipeline at least 10x faster" (run r8d0a8d799d) with outputs required identical. The engine locked a contract with metric speedup and target 10 for run r8d0a8d799d, gated on exact output equality. Evolution reached a measured 10.90x speedup at evaluation 16 of 200 in run r8d0a8d799d, using only the cheap diff operator, seed 47, replayable. The winning program discovered numpy vectorization inside the mutable region and wrapped its arrays to stay list-compatible so the equality gate kept passing.

Full report for this run: docs/gallery/r8d0a8d799d-report.md
Related MCP server: multivon-mcp
Any agent can join a run
One run was served over MCP streamable HTTP and worked simultaneously by a Claude Code session and a Codex session. Both called join_run on the same population, both submitted gate-checked mutations, and the islands table records both runtimes (run rda6528a177, 4 non-seed programs).

Quickstart
git clone https://github.com/RightNow-AI/autoevolve && cd autoevolve && uv sync
uv run autoevolve run --evaluator evaluators/python-speedup --budget-evals 200 --target 10 --operators diff
uv run autoevolve watch <run_id>Add --parallel N to drive one run with N workers. A cycle spends nearly all
of its wall clock waiting on a model call, so workers overlap and throughput
scales close to linearly: run r0217367e52 measured 12.6 seconds per child on
four workers against 62.7 in run r8d0a8d799d on one.
Model access resolves from the environment: set AUTOEVOLVE_LOCAL_BASE_URL for a local OpenAI-compatible engine (no key needed), or OPENAI_API_KEY with AUTOEVOLVE_MODEL (plus optional OPENAI_BASE_URL) for a cloud endpoint. Every run requires a budget bound and every number it reports carries its run id.
How it works
English in, contract out. Before any compute burns, autoevolve synthesizes or loads
evaluate.py, measures the baseline three times, computes a feasibility ceiling where possible, and locks the contract. A target above the ceiling stops the run before evolution with the analysis as the result.The agent is the mutation operator. Claude Code and Codex sessions mutate candidates. They can profile, read failure reasons, and debug the evaluator. The cheap diff path handles bulk throughput; agentic dives handle the hard jumps.
The population outlives sessions. All evolution state lives in one SQLite store owned by the autoevolve server. Workers are stateless and disposable. Any MCP-speaking agent joins a run mid-flight with join_run.
It gets smarter every run. Top lineage diffs are distilled into a discovery ledger that future runs sample into mutation context.
It evolves itself. Operator selection is a persistent per-domain UCB1 bandit over measured child-improvement rates.
Surfaces
surface | shape |
CLI |
|
MCP server + skill |
|
GitHub issue mode | issue in, contract proposal comment, evolve:approved label as the consent record, evolution with milestone comments, artifact-embedded PR out |
Dashboard | self-contained dashboard.html plus evolution.gif plus lineage poster per run |
Use it on your own repository
Copy autoevolve/gh/workflow-template.yml to .github/workflows/evolve.yml,
create the evolve and evolve:approved labels, and add a model endpoint
secret. Then open an issue titled evolve: make X faster. autoevolve replies
with the contract it would measure against, and nothing executes until a
maintainer with write access applies evolve:approved. That label is the
consent record. The run ends with a pull request carrying the winning code,
the report, and the artifacts.
Evaluator packs
Four bundled packs under evaluators/, each obeying docs/CONTRACT.md:
python-speedup, triton-kernel (honest CPU mock without a GPU, roofline ceiling
with one), routing-heuristic, symbolic-regression on the Nguyen-7 benchmark.
Write your own with autoevolve init <name>.
Research campaigns
Four campaign packs under campaigns/ aim the engine at discovery: kernel-frontier, arch-search, algorithm-frontier, equation-discovery. Every campaign enforces the promotion ladder and the claims policy in code; a measured claim without a run id fails the test suite.
Any domain, not just code
Nothing in the engine knows what a kernel or a graph is. The evaluator is the domain, so adding one means writing roughly two hundred lines, not changing the system. What decides whether a domain works is whether a candidate answer can be checked by a program, cheaply, with partial credit. docs/DOMAINS.md gives the three questions, the certificate taxonomy, and worked answers for AI algorithms, space, vehicles, vision, language, and mathematics, including which parts of each are honestly out of reach.
Honesty
docs/HONESTY.md is enforced, not aspirational. Measured-or-null, run ids on every number, failure reported as a first-class result, proxy wins always labeled proxy wins.
Docs
docs/ARCHITECTURE.md is the normative module and interface spec.
docs/CONTRACT.md is the normative evaluator contract.
docs/CAMPAIGNS.md is the campaign pack format.
CLAUDE.md is the constitution this repository is built under.
License
Apache-2.0
Available Tools
9 toolsbestA
Read the best measured programs in a run.
Call this at checkpoints or after closure when you need the current leaders. The Engine
owns ranking and returns its program records in best-first order.
Returns: list[dict] containing up to k ranked program records, or the standard error dict.
Mistake to avoid: never call a candidate best without using this measured ranking.
Inputs: run_id (required), k. Returns: result
discoveriesA
Search reusable measured discoveries for a domain.
Call this before a mutation when the parent bundle needs broader evidence or when a query
can focus the search on a failure, operator, or implementation technique.
Returns: list[dict] of discovery records matching domain and query, or the standard error
dict.
Mistake to avoid: never treat a discovery as proof for the current child until it is
measured by submit_child.
Inputs: domain (required), query. Returns: result
get_contractA
Read the immutable scoring contract before doing worker work.
Call this before join_run and reread it whenever the metric, gate, target, or budget is
unclear. Treat every returned contract field as law for the life of the run.
Returns: {"goal", "domain", "metric", "maximize", "baseline", "target", "gate",
"budget", "descriptors", "feasibility", "plateau_n"}, or the standard error dict.
Mistake to avoid: never infer or rewrite the metric, gate, target, or budget.
Inputs: run_id (required). Returns: object
join_runA
Join a run and receive this worker's island assignment.
Call this after get_contract and before the first next_parent call. Pass a useful runtime
label such as claude-code, codex, or a local worker identifier.
Returns: {"island": int}, or {"error": true, "kind": str, "message": str}.
Mistake to avoid: never invent an island number or reuse another worker's assignment.
Inputs: run_id (required), runtime (required). Returns: object
lineageA
Read the recorded ancestry for one evaluated program.
Call this when explaining how a strong program was reached or when choosing which prior
operators and changes deserve closer study.
Returns: list[dict] of recorded lineage nodes for program_id, or the standard error dict.
Mistake to avoid: never reconstruct ancestry from memory or filenames.
Inputs: program_id (required). Returns: result
next_parentA
Get the parent and evidence needed for one mutation cycle.
Call this at the start of every worker cycle. Read the parent files, every inspiration,
every discovery, the operator hint, and any crossover parent before editing.
Returns: {"parent": Program fields, "parent_files": {path: content}, "inspirations":
[{"program": Program fields, "scores": dict, "files_excerpt": {path: content}}],
"discoveries": [str], "operator_hint": str|null, "parent_sample_seq": int, and
optional "crossover_parent" and "crossover_files"}, or the standard error dict.
Mistake to avoid: never mutate before reading inspirations and discoveries.
Inputs: island (required), run_id (required). Returns: object
open_runA
Open and lock an evolution run for a measured goal.
Call this once when no existing run matches the work. The Engine creates the evaluator
contract, measures its baseline, and refuses an unbounded budget.
Returns: {"run_id": str, "contract": dict} plus any Engine feasibility fields, or
{"error": true, "kind": str, "message": str}.
Mistake to avoid: never leave max_evals, wall_clock_s, and max_cost_usd all unset.
Inputs: goal_text (required), seed, target, workers, +4 more. Returns: object
run_statusA
Read closure state, progress, budget, and artifact paths for a run.
Call this after every submit_child and at the end of every cycle summary. Stop requesting
parents when status says the run is closed.
Returns: {"status": str, "curve": [[eval_idx, best_fitness]], "plateau": bool,
"budget_remaining": dict, "islands": object, "artifacts": {"gif": path|null,
"poster": path|null, "dashboard": path|null}}, or the standard error dict.
Mistake to avoid: never omit the artifact paths or continue after a closed status.
Inputs: run_id (required). Returns: object
submit_childA
Submit full child file contents for evaluation and archive insertion.
Call this once after producing one mutation from the current parent bundle. Echo its
parent_sample_seq, use the selected or suggested operator, and explain reasoning in notes.
Returns: {"program_id": str, "gate_passed": bool, "scores": dict, "fitness": number,
"archive_improved": bool, "best_fitness": number, "plateau": bool,
"budget_remaining": dict}, or the standard error dict.
Mistake to avoid: never modify content outside EVOLVE-BLOCK markers. The Engine rejects it.
Inputs: files (required), run_id (required), operator (required), parent_id (required), +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool serves a distinct, non-overlapping role in the evolution workflow: run lifecycle (open_run, join_run, run_status), contract access (get_contract), mutation cycle (next_parent, submit_child), and result/history lookup (best, lineage, discoveries). There is no ambiguity about which tool to use for a given task.
Naming mixes verb-noun forms (open_run, get_contract, join_run, submit_child) with noun-only (lineage, discoveries), adjective-noun (next_parent), and noun-noun (run_status). While all names use lowercase_with_underscores and are descriptive, the lack of a consistent pattern makes tool names less predictable.
Nine tools is well-scoped for the server's purpose. Each tool covers a necessary step in the evolutionary run lifecycle without redundancy or bloat, fitting comfortably in the typical 3-15 range.
The tool set provides complete coverage for an evolution run: creation, contract inspection, joining, mutate/submit cycle, status monitoring, and outcome retrieval. No critical operations are missing; lifecycle end is handled via run_status and Engine state.
Maintenance
Related MCP Connectors
Remote MCP server for The Colony — a social network for AI agents (posts, DMs, search, marketplace).
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for autonomous agent minting, crossbreeding, and evolution. Mint new AI agents with genetic lineage tracking, cross-breed capabilities between agents, run evolution cycles, and discover complementary agents in the HiveBazaar marketplace.MIT

multivon-mcpofficial
AlicenseAqualityBmaintenanceMCP server that gives AI coding agents direct access to evaluation tools.23Apache 2.0- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.79 npm10MIT
- AlicenseBqualityCmaintenanceMCP server that provides a live coordination layer for AI agents, including attributable handoffs, a shared event ledger, atomic work-claiming, and advisory file leases to prevent collisions.279AGPL 3.0