Skip to main content
Glama

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

evolution timelapse of run r8d0a8d799d

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.

lineage poster of run r8d0a8d799d

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).

dual worker lineage of run rda6528a177

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

  1. 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.

  2. 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.

  3. 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.

  4. It gets smarter every run. Top lineage diffs are distilled into a discovery ledger that future runs sample into mutation context.

  5. It evolves itself. Operator selection is a persistent per-domain UCB1 bandit over measured child-improvement rates.

Surfaces

surface

shape

CLI

autoevolve init|run|watch|join|report|render|serve|campaign

MCP server + skill

autoevolve serve [--http]; the skill in skill/ teaches any agent the worker loop

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 tools
bestA

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

    A4.3/5.0

    Scored across 9 tools

    Disambiguation5/5

    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 Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.
      79 npm
      10
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP 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.
      27
      9
      AGPL 3.0