Run Optimizer

run-optimizer — one runner, a registry of agents

An optimizer is the agent that reads the current capability + the failure diagnosis and proposes an edit. Every such agent follows the same contract: given a working directory (a copy of the parent candidate) and an INSTRUCTIONS.md, edit the files in place. Because the contract is identical, one runner serves them all — the only thing that varies per agent is the shell command, which lives as a row in optimizers/registry.yaml. Adding an optimizer is one YAML row, not a new skill directory.

How it works

1. The loop calls run.py --name --workdir --prompt INSTRUCTIONS.md.
2. The runner reads the registry, resolves the row, and expands its

command_template (placeholders below) into argv.

1. It runs that command with cwd = workdir, so the agent edits the candidate

files directly. Output is summarized as JSON (returncode, auth_present, stdout_tail).

Template placeholders

| placeholder | expands to | |---|---| | {workdir} | the candidate working copy (also the cwd) | | {prompt} | path to INSTRUCTIONS.md | | {prompt_text} | the contents of INSTRUCTIONS.md (for CLIs that take the prompt inline) | | {model} | the resolved model id; an empty {model} drops itself and a preceding -m/--model | | {self_dir} | the runner's own scripts dir (used by the mock row) | | ${VAR} | environment expansion (the generic/openclaw/antigravity escape hatches read their command from env) |

Choosing an optimizer (--name / optimizer_skill)

mock, generic, claude-code, codex, gemini-cli, opencode, cursor, droid (Factory Droid), copilot (GitHub Copilot CLI), kimi, pi, antigravity, openclaw, ibm-bob. Per-CLI install / auth / flag details are in references/.md.

• mock is fully offline (runs a shipped JSON-driven editor, never a network

CLI), so the end-to-end proof slice costs nothing and never flakes.

• generic / openclaw / antigravity read their command from

CAPEVOLVE_OPTIMIZER_CMD / CAPEVOLVE_OPENCLAW_CMD / CAPEVOLVE_ANTIGRAVITY_CMD — the escape hatch that makes "any optimizer" literal. (antigravity is a wrapper because its auth is Google-Sign-In-only and its headless approve flag is unconfirmed.)

• cursor, droid, copilot, kimi, pi are verified

headless commands; matches the agent set supported by obra/superpowers.

Standalone use

# list known optimizers
python scripts/run.py --list
# drive one agent over a candidate dir
python scripts/run.py --name claude-code --workdir ./cand --prompt ./cand/INSTRUCTIONS.md --model claude-opus-4-6

In a run, the orchestrator builds this command for you from the spec's optimizer_skill (the optimizer NAME) and optimizer_model.

Headless JSON cost capture (optional, best-effort)

Coding-agent CLIs can emit a structured result that carries the exact spend. Pass --json (or set CAPEVOLVE_OPTIMIZER_JSON=1) and the runner appends the registry row's json_flag to the command, then parses total_cost_usd (and token usage) out of the output:

python scripts/run.py --name claude-code --json \
  --workdir ./cand --prompt ./cand/INSTRUCTIONS.md --model claude-opus-4-6
# -> {... "cost": {"total_cost_usd": 0.0123, "tokens": 4210}}

Per CLI (verify with --help):

• claude-code — json_flag: --output-format json; the JSON result has

total_cost_usd, usage, and per-model cost under modelUsage. Add --json-schema '' (via --json-schema here, or CAPEVOLVE_OPTIMIZER_JSON_SCHEMA) to also get .structured_output for a decision step. The runner only appends --json-schema when the row's json_flag contains --output-format.

• codex — json_flag: --json (a JSONL stream); pair with

codex exec --json --output-last-message when you want the final message on disk. The runner parses the last JSON line for cost/usage.

• gemini-cli — json_flag: --output-format json; total_cost_usd/usage are

parsed when present.

This is strictly additive. With no --json, or for a row whose json_flag is empty (mock, generic, opencode, openclaw, ibm-bob), nothing changes — the optimizer runs prose-fed exactly as before, and mock stays fully offline. If the output isn't parseable JSON, cost.total_cost_usd is null and the loop continues without a cost figure (never an error).

Back-compat

A spec that still names an old per-CLI optimizer skill (claude-code, ibm-bob, …) resolves to the registry row of the same name, so existing specs keep working without edits.

References

• references/.md — install, auth, and flags for each CLI.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skillberry-ai
• Source: skillberry-ai/cap-evolve
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.