Codex Auto Effort

Local dynamic reasoning-effort routing for the Codex CLI, with configurable bounds, explicit overrides, and transparent tier selection.

Note

This is an unofficial community project. It is not affiliated with or endorsed by OpenAI.

Why

Codex currently accepts a fixed model_reasoning_effort setting. Real work is not fixed: a typo should be fast, while a flaky-test investigation or architecture review may benefit from deeper reasoning.

codex-auto examines the initial prompt, selects an effort, and launches Codex with a per-run config override. It does not rewrite your Codex configuration.

Codex Auto -> high (debugging or failure investigation)

Features

• Routes among low, medium, high, and xhigh
• Configurable minimum, maximum, and default effort
• Explicit CLI and natural-language overrides
• Explains every routing decision before launch
• Dry-run mode for inspecting decisions without starting a Codex task
• Forwards normal options and prompts to the installed Codex CLI
• Automatically locates the current Codex Desktop CLI executable on Windows

Requirements

• Windows
• PowerShell 7 (pwsh)
• Codex CLI or Codex Desktop with its bundled CLI

Install

Clone the repository and copy both launchers into a directory on your PATH:

git clone https://github.com/MECMwithShawn/codex-auto-effort.git
Set-Location codex-auto-effort
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
Copy-Item codex-auto.ps1, codex-auto.cmd "$HOME\bin"

If $HOME\bin is not already on your user PATH, add it and then open a new terminal:

$bin = "$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $bin) {
    [Environment]::SetEnvironmentVariable('Path', "$userPath;$bin", 'User')
}

Verify the installation:

codex-auto --quiet -- --version

Usage

Start Codex normally through the wrapper:

codex-auto "fix the typo in README.md"
codex-auto "debug the repeated integration-test failure"
codex-auto "review this multi-file refactor"

Preview the decision without launching Codex:

codex-auto --dry-run -- "root-cause this production deadlock"

Bound the selected effort:

codex-auto --min medium --max high -- "debug this flaky test"

Force a tier for one launch:

codex-auto --effort xhigh -- "analyze this architecture"

Everything after -- is forwarded unchanged to Codex:

codex-auto --max high -- --search -C C:\src\my-project "investigate this regression"

Default routing policy

Task signal	Typical effort
Quick, brief, typo, formatting, or simple edit	low
No strong signal	medium
Debugging, code review, architecture, or broad refactor	high
Several difficult signals or high-stakes analysis	xhigh

The default bounds are low..xhigh. Stronger signals add together, so a repeated production failure can route higher than an ordinary debugging task.

Configuration

Command-line options:

--effort auto|none|low|medium|high|xhigh|max
--min    none|low|medium|high|xhigh|max
--max    none|low|medium|high|xhigh|max
--dry-run
--quiet
--help

Environment defaults:

Variable	Default	Purpose
CODEX_AUTO_DEFAULT	medium	Tier used without a strong signal
CODEX_AUTO_MIN	low	Minimum selectable tier
CODEX_AUTO_MAX	xhigh	Maximum selectable tier
CODEX_AUTO_CLI_PATH	auto-detected	Explicit path to codex.exe

Example:

$env:CODEX_AUTO_MIN = 'medium'
$env:CODEX_AUTO_MAX = 'high'
codex-auto "review this change"

Limitations

• Routing occurs once, before the CLI process starts.
• The wrapper cannot change effort during an active turn.
• It does not control tasks started directly inside Codex Desktop.
• Prompt classification is intentionally local and deterministic; no extra API request is made to choose the tier.

True per-turn or mid-turn dynamic effort requires native support in Codex. See openai/codex#8649.

Testing

Run the dependency-free test script:

pwsh -NoProfile -File tests/codex-auto.tests.ps1

License

MIT