Skip to content

Optimization

CodexOpt supports three maintained optimization modes.

Heuristic Engine

The heuristic engine is local, fast, deterministic, and offline.

It applies safe transforms such as:

  • whitespace normalization
  • blank-line compaction
  • duplicate adjacent line removal
  • skill frontmatter synthesis and trimming

Use it when you want predictable cleanup with no model dependency.

Reflective Engine

The reflective engine is the recommended path for Codex users. It follows the SkillOpt/GEPA loop in-house: evaluate a document on tasks, collect textual feedback, propose a focused rewrite, and keep the rewrite only if it improves a held-out validation split.

The easiest command is:

codexopt improve

That previews an offline run. To use Codex as both optimizer and judge:

codexopt improve --live
codexopt improve --live --apply

You can also run it directly:

codexopt --config codexopt.yaml optimize skills --engine reflective
codexopt --config codexopt.yaml optimize agents --engine reflective --file AGENTS.md

Relevant config:

reflective:
  optimizer_model: null
  judge_model: null
  reward_mode: "tiered"
  minibatch_size: 3
  max_iterations: 6
  edit_budget: 12
  valset_ratio: 0.34
  max_rollouts: 60

Set optimizer_model and judge_model to codex or openai/<model> when you want live reflective mutation without passing --live.

SkillOpt Engine

The skillopt engine applies a single-shot SkillOpt-style gate to SKILL.md files:

  • split task evidence into train and validation slices
  • generate candidate skill edits with heuristic transforms
  • reject candidates that exceed the edit budget
  • accept only candidates that improve validation score by the configured minimum delta
  • use executable rollout pass rate as the validation score when JSON rollout tasks are configured
  • record rejected candidates and rejection reasons in optimize.json

Use it for skill files when you have task evidence configured:

codexopt --config codexopt.yaml optimize skills \
  --engine skillopt \
  --glob ".codex/skills/**/SKILL.md"

Relevant config:

optimization:
  engine: "skillopt"
  skillopt_train_ratio: 0.67
  skillopt_edit_budget: 24
  skillopt_validation_delta: 0.01

Legacy GEPA Engine

--engine gepa is deprecated because it targeted an older gepa.optimize_anything API. CodexOpt records a fallback reason and uses heuristic optimization instead. Use --engine reflective or codexopt improve --live for the maintained GEPA-inspired workflow.