autoevolve AGENTS.md

Autoevolve agent instructions

Constitution and scope

CLAUDE.md is the repository constitution. Read its relevant sections before changing product behavior. Treat docs/ARCHITECTURE.md as the normative module and seam map. Keep each unit inside its owned paths and do not move evolution logic into adapters.

What autoevolve does

Autoevolve measures a population of code candidates against one locked contract. Workers propose mutations, and the Engine owns validation, evaluation, ranking, storage, budgets, and closure. A run delivers either its measured target or evidence for the best ceiling reached within its budget.

Connect

For Codex, register autoevolve in the active MCP configuration with either:

• stdio command uv run autoevolve serve
• Streamable HTTP endpoint http://127.0.0.1:8747/mcp

Use the MCP configuration format supported by the active Codex host. Once unit U5 lands, a human or agent may also drive the CLI surface through autoevolve join. Do not assume the CLI command exists before that unit is present.

Python can connect directly to the server without a subprocess:

import asyncio

from mcp import Client

from autoevolve.mcp.server import build_server


async def read_contract(run_id: str) -> object:
    async with Client(build_server()) as client:
        return await client.call_tool("get_contract", {"run_id": run_id})


asyncio.run(read_contract("run_01"))

Claude Code uses these client-specific registration commands:

claude mcp add --transport stdio autoevolve -- uv run autoevolve serve
claude mcp add --transport http autoevolve http://127.0.0.1:8747/mcp

A project-scoped Claude Code HTTP entry uses http:

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

Worker loop

Follow this cycle exactly:

1. Call open_run only when no suitable run exists. Supply at least one budget bound.
2. Call get_contract before joining or editing. Read the metric, direction, gate, target, descriptors, and budget.
3. Call join_run once with a useful runtime label. Keep the returned island assignment.
4. Call next_parent at the start of each cycle.
5. Read the full parent, every inspiration and score, every file excerpt, every discovery, the operator hint, and any crossover fields.
6. Choose a narrow cheap diff or a deeper evidence-gathering pass.
7. Submit one child with submit_child. Send full changed file contents and honest notes.
8. Read the gate result and measured scores. Do not infer a score from a local profile.
9. Call run_status after each submission. End the cycle summary with all artifact paths.
10. Repeat until run_status.status records closure.