CodexOpt
Benchmark and optimize AGENTS.md and SKILL.md for Codex.
A lightweight CLI to measure quality, detect issues, and generate optimized instruction files - locally or with AI.
Get Started in Seconds
Install with uv or pip and start optimizing
Install CodexOpt
Choose uv (recommended) or pip
uv sync --extra devpip install -e ".[dev]"Initialize & Scan
Set up and analyze your project
uv run codexopt inituv run codexopt scanPowerful Features
A complete toolkit to evaluate and improve your Codex instruction assets
Project Scanning
Detect issues in agents and skill files automatically.
Benchmark Scoring
Sub-scores and natural language feedback on quality.
Heuristic Optimizer
Local, fast optimization engine - no API needed.
GEPA Engine
AI-powered optimization for deeper improvements.
Safe Apply Flow
Automatic backups before any changes are applied.
Markdown Reporting
Generate detailed reports from optimization runs.
From Scan to Report
A structured pipeline to measure and improve instruction quality
uv run codexopt inituv run codexopt scanuv run codexopt benchmarkuv run codexopt optimize agents --file AGENTS.mduv run codexopt optimize skills --glob ".codex/skills/**/SKILL.md"uv run codexopt apply --kind agentsuv run codexopt report --output codexopt-report.mdTwo Optimization Engines
Choose the right engine for your needs
Heuristic Engine
Default - runs locally
Fast, deterministic optimization using rule-based heuristics. No API keys or external calls required. Perfect for CI/CD integration and quick iterations.
GEPA Engine
AI-powered - optional
Leverages large language models for deeper, context-aware optimization. Produces more nuanced improvements for complex instruction files.
Ship Better Codex Instructions
CodexOpt is open source, MIT licensed, and built to make your Codex agents more effective.