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.