Skip to content

Configuration

CodexOpt reads codexopt.yaml by default.

Example Config

version: 1
targets:
  agents_files:
    - AGENTS.md
    - "**/AGENTS.md"
    - "**/AGENTS.override.md"
  skills_globs:
    - ".codex/skills/**/SKILL.md"
    - "**/.codex/skills/**/SKILL.md"
    - ".agents/skills/**/SKILL.md"
    - "**/.agents/skills/**/SKILL.md"
  exclude_globs:
    - ".git/**"
    - ".codexopt/**"
    - ".venv/**"
    - "node_modules/**"
    - "reference/**"
output:
  root_dir: ".codexopt"
evidence:
  task_files: []
  issue_files: []
optimization:
  engine: "heuristic"
  min_apply_delta: 0.01
  max_metric_calls: 60
  reflection_model: null
  skillopt_train_ratio: 0.67
  skillopt_edit_budget: 24
  skillopt_validation_delta: 0.01

Sections

targets

Controls where CodexOpt looks for instruction assets.

  • agents_files: glob patterns for AGENTS.md
  • skills_globs: glob patterns for Codex SKILL.md files, including .codex/skills and .agents/skills repo roots
  • exclude_globs: paths to ignore during discovery

output

Controls artifact location.

  • root_dir: where runs, state, and backups are written

evidence

Optional files that improve benchmarking and optimization quality.

  • task_files: markdown or JSON task lists
  • issue_files: markdown or JSON issue / review exports

Markdown task files influence scoring and feedback. JSON task files can also define executable rollouts for skillopt validation.

Executable rollout task example:

[
  {
    "name": "skill-smoke",
    "description": "Verify the skill supports release validation.",
    "command": "python scripts/check_release_skill.py",
    "timeout_seconds": 30,
    "expected_stdout_contains": "ok"
  }
]

Codex-backed rollout example:

[
  {
    "name": "codex-release-task",
    "backend": "codex",
    "description": "Run Codex against a candidate skill.",
    "codex_prompt": "Use the release skill to update CHANGELOG.md for a patch release.",
    "timeout_seconds": 120,
    "expected_final_response_contains": "CHANGELOG.md",
    "expected_file_change": "CHANGELOG.md",
    "expected_file_contains": {
      "path": "CHANGELOG.md",
      "contains": "Patch"
    }
  }
]

When rollout tasks are present, skillopt copies the repo to a temporary directory, writes each candidate SKILL.md, runs the command there, and gates acceptance on held-out rollout pass rate.

optimization

  • engine: heuristic, reflective, or skillopt
  • min_apply_delta: minimum score gain required to keep a candidate
  • max_metric_calls: legacy GEPA search budget
  • reflection_model: legacy GEPA reflection model
  • skillopt_train_ratio: fraction of task evidence used for skill candidate proposal
  • skillopt_edit_budget: maximum line edit operations allowed for a skill candidate
  • skillopt_validation_delta: minimum held-out validation gain required for acceptance

Using a Non-default Config

--config is a global option and must appear before the subcommand:

codexopt --config codexopt.yaml benchmark
codexopt --config codexopt.yaml optimize agents --file AGENTS.md