Autoevolve Worker

Autoevolve worker

What autoevolve is

Autoevolve runs a population of code candidates against a locked evaluator contract. Workers propose mutations, while the Engine measures every accepted child and records the population. The run ends with a target hit or evidence for the best ceiling reached within its budget.

The contract

Read get_contract before joining or editing anything. The metric, direction, correctness gate, target, descriptors, and budget are law for the life of the run. Do not replace them with a proxy, and do not promise an unmeasured outcome. The product promise is the target or an evidence-backed ceiling.

Every tool can return this error dictionary:

{"error": true, "kind": "ValueError", "message": "What failed and how to recover."}

Check error before using any result. For full argument and return tables, read reference.md.

Connect the worker

Install this directory as the project skill at .claude/skills/autoevolve-worker/. Copy it or symlink it so that .claude/skills/autoevolve-worker/SKILL.md exists.

Register the stdio server in Claude Code:

claude mcp add --transport stdio autoevolve -- uv run autoevolve serve

Or start the HTTP server and register its Streamable HTTP endpoint:

claude mcp add --transport http autoevolve http://127.0.0.1:8747/mcp

Project scope may be recorded in .mcp.json. The HTTP type is http:

{
  "mcpServers": {
    "autoevolve": {
      "type": "http",
      "url": "http://127.0.0.1:8747/mcp"
    }
  }
}

The worker loop

Use this concrete cycle:

1. If no run exists, call open_run with at least one budget bound.
2. Call get_contract. State the metric, direction, gate, target, and configured budget plainly.
3. Call join_run once for this worker and keep the returned island assignment.
4. Call next_parent for that island.
5. Read every parent file, inspiration, score, file excerpt, discovery, operator hint, and crossover field before deciding on a mutation.
6. Choose a cheap diff or an agentic dive. Change only what the evidence supports.
7. Call submit_child with full file contents and honest notes.
8. Read the returned gate result and measured scores. A failed gate is information. Read its reason.
9. Call run_status. End the cycle summary with the GIF, poster, and dashboard paths.
10. Repeat from next_parent until run_status says the run is closed.

open_run

{
  "call": {
    "tool": "open_run",
    "arguments": {
      "goal_text": "Reduce p95 latency without changing results",
      "evaluator_ref": "evaluators/latency",
      "max_evals": 200,
      "wall_clock_s": null,
      "max_cost_usd": null,
      "workers": 4,
      "seed": 17
    }
  },
  "result": {
    "run_id": "run_01",
    "contract": {"metric": "p95_ms", "maximize": false, "gate": "exact parity"}
  }
}

get_contract

{
  "call": {"tool": "get_contract", "arguments": {"run_id": "run_01"}},
  "result": {
    "goal": "Reduce p95 latency without changing results",
    "domain": "python-speedup",
    "metric": "p95_ms",
    "maximize": false,
    "baseline": 42.1,
    "target": 20.0,
    "gate": "exact parity",
    "budget": {"max_evals": 200, "wall_clock_s": null, "max_cost_usd": null},
    "descriptors": [],
    "feasibility": null,
    "plateau_n": 150
  }
}

join_run

{
  "call": {
    "tool": "join_run",
    "arguments": {"run_id": "run_01", "runtime": "claude-code"}
  },
  "result": {"island": 2}
}

next_parent

{
  "call": {"tool": "next_parent", "arguments": {"run_id": "run_01", "island": 2}},
  "result": {
    "parent": {"id": "prog_18", "operator": "targeted_diff", "island": 2},
    "parent_files": {
      "solution.py": "# EVOLVE-BLOCK-START\ndef solve(data):\n    return parse(data)\n# EVOLVE-BLOCK-END\n"
    },
    "inspirations": [
      {
        "program": {"id": "prog_11", "operator": "profile_guided"},
        "scores": {"p95_ms": 27.4},
        "files_excerpt": {"solution.py": "cached = lookup[key]"}
      }
    ],
    "discoveries": ["Repeated parsing dominated the last three valid children."],
    "operator_hint": "profile_guided"
  }
}

submit_child

{
  "call": {
    "tool": "submit_child",
    "arguments": {
      "run_id": "run_01",
      "parent_id": "prog_18",
      "operator": "profile_guided",
      "files": {"solution.py": "# EVOLVE-BLOCK-START\noptimized()\n# EVOLVE-BLOCK-END\n"},
      "notes": "Cache the parsed lookup after the bundle showed repeated parsing cost."
    }
  },
  "result": {
    "program_id": "prog_19",
    "gate_passed": true,
    "scores": {"p95_ms": 24.8},
    "fitness": 24.8,
    "archive_improved": true,
    "best_fitness": 24.8,
    "plateau": false,
    "budget_remaining": {"max_evals": 181}
  }
}

best

{
  "call": {"tool": "best", "arguments": {"run_id": "run_01", "k": 2}},
  "result": [
    {"program_id": "prog_19", "fitness": 24.8, "scores": {"p95_ms": 24.8}},
    {"program_id": "prog_18", "fitness": 26.1, "scores": {"p95_ms": 26.1}}
  ]
}

lineage

{
  "call": {"tool": "lineage", "arguments": {"program_id": "prog_19"}},
  "result": [
    {"program_id": "prog_seed", "parent_id": null, "operator": "seed"},
    {"program_id": "prog_18", "parent_id": "prog_seed", "operator": "targeted_diff"},
    {"program_id": "prog_19", "parent_id": "prog_18", "operator": "profile_guided"}
  ]
}

discoveries

{
  "call": {
    "tool": "discoveries",
    "arguments": {"domain": "python-speedup", "query": "parsing"}
  },
  "result": [
    {
      "id": "d1234567890",
      "domain": "python-speedup",
      "text": "Cache immutable parse results after the parity gate.",
      "source_run": "r1234567890",
      "source_programs": ["p1234567890"],
      "created_at": "2026-08-03T00:00:00+00:00"
    }
  ]
}

run_status

{
  "call": {"tool": "run_status", "arguments": {"run_id": "run_01"}},
  "result": {
    "status": "running",
    "curve": [[0, 42.1], [19, 24.8]],
    "plateau": false,
    "budget_remaining": {"max_evals": 181},
    "islands": {"active": 4},
    "artifacts": {
      "gif": ".autoevolve/runs/run_01/progress.gif",
      "poster": ".autoevolve/runs/run_01/poster.png",
      "dashboard": ".autoevolve/runs/run_01/dashboard.html"
    }
  }
}

EVOLVE-BLOCK discipline

If a file contains EVOLVE-BLOCK markers, content outside the markers is frozen. Files without markers are fully mutable, and new files are allowed, but do not use that rule to route around a marked file's frozen content. Always submit full contents for every changed file.

Right:

CONFIG = {"mode": "safe"}

# EVOLVE-BLOCK-START
def solve(data):
    return optimized_path(data)
# EVOLVE-BLOCK-END

PUBLIC_API = "v1"

Wrong:

CONFIG = {"mode": "unsafe"}  # Changed outside the mutable region.

# EVOLVE-BLOCK-START
def solve(data):
    return optimized_path(data)
# EVOLVE-BLOCK-END

PUBLIC_API = "v2"  # Changed outside the mutable region.

The Engine compares the child with the parent and rejects marker violations. Do not submit a known violation to see whether it passes.

Choosing depth

Use the cheap diff path for a small, local, evidence-backed change. Typical cases include one branch condition, one allocation, one cache, or one focused algorithm replacement. Keep the diff narrow and submit quickly so measurement can guide the next cycle.

Use an agentic dive when the bundle shows a complex failure, unclear bottleneck, interacting files, or a plateau that small edits have not moved. Profile or inspect the relevant code, read the failure reason, compare strong and weak inspirations, reason about the operator hint, and then edit. The deeper path still ends with one child and one measured submission.

Before every mutation, read the inspirations and discoveries. They are the population's working memory. They guide a proposal, but only submit_child can establish a score for that proposal.

Honesty rules

• Never claim a score that did not come from submit_child.
• Never turn a failed correctness gate into a performance claim.
• Report a failed gate and its reason as useful information.
• Never present a discovery, local profile, or intuition as the child's measured result.
• End every cycle summary with the run_status artifact paths for GIF, poster, and dashboard.
• Keep the run id and program id beside every benchmark claim.
• State whether the run stopped on target, budget, plateau, infeasibility, or another recorded state.

Stopping

Stop requesting parents when run_status.status says the run is closed. Call best and report the best measured fitness with its program id. Print the GIF, poster, and dashboard paths from run_status.artifacts, even when a path is null. Explain the recorded stop reason without turning a budget or plateau result into a target hit.