evolve

/evolve — Start Evolution

User provides: repo path, benchmark command, objectives (list of {name, direction} specs), and optionally max evaluations.

Step 1 — Deterministic setup

lobster (@openclaw/lobster) is bundled as a dependency and installed automatically with this package. If available, setup and teardown run as atomic lobster pipelines. If for some reason lobster is missing from $PATH, the same steps run as individual exec calls — no functionality is lost, lobster only adds atomicity and better error reporting.

With lobster

Run all pre-evolution setup as a single deterministic lobster workflow. This is atomic: if any step fails, the exact failure step is reported and nothing proceeds.

lobster action:run pipeline:"./plugin/workflows/evo-setup.lobster" args:{
  "repo": "<repo_path>",
  "benchmark": "<benchmark_cmd>",
  "objectives": "[{\"name\": \"score\", \"direction\": \"max\"}]"
}

The workflow handles:

• Validate repo is clean (git status --porcelain)
• Run baseline benchmark, capture seed fitness
• git tag seed-baseline
• Create memory/ directory structure
• Initialize ~/clawd/canvas/ for dashboard

Parse the baseline fitness from run_baseline.stdout (last line — whitespace-separated numbers for "numbers" format, or JSON dict for "json" format).

Then call the MCP tools to record it:

• evo_init with user's config (repo, benchmark, objectives, max_evals)
• evo_report_seed with the baseline fitness values as list[float]

Without lobster

Fall back to running each step with individual exec calls (same operations, not atomic).

Step 2 — Code analysis (MapAgent)

Spawn MapAgent to identify optimization targets:

sessions_spawn agentId:map_agent

MapAgent reads the benchmark entry file, traces the call chain (using /oracle if available), and calls evo_register_targets.

Step 3 — Approval gate: confirm targets before committing budget

After MapAgent completes, present identified targets to the user and ask for confirmation before spending evaluation budget: