Codex Plugin Reasoning Effort Levels: Understanding the Six Valid Options and Configuration Methods

The OpenAI Codex plugin supports six reasoning effort levels—none, minimal, low, medium, high, and xhigh—controlled via the --effort CLI flag or the .codex/config.toml configuration file.

The openai/codex-plugin-cc repository provides a command-line interface for interacting with Codex models, allowing developers to fine-tune how much computational "thinking" the model applies to each task. Understanding the available reasoning effort levels and their validation logic helps you optimize performance for different coding scenarios, from quick refactors to complex architectural decisions.

Supported Reasoning Effort Values

The plugin defines a strict whitelist of six valid effort levels that control model deliberation depth. According to the source code in plugins/codex/scripts/codex-companion.mjs at line 71, the allowed values are:

• none – No additional reasoning effort
• minimal – Bare minimum deliberation
• low – Reduced computational depth
• medium – Standard reasoning effort
• high – Extended computational analysis
• xhigh – Maximum reasoning effort available

These values are stored in a VALID_REASONING_EFFORTS set that the validation logic checks against when parsing user input.

Using the --effort Command-Line Flag

You specify the desired reasoning level using the --effort flag on supported sub-commands. As documented in plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 21‑35) and implemented in the argument parser, the flag accepts any of the six valid values.

# Run a task with minimal reasoning effort

codex task --effort minimal "refactor the authentication module"

# Run a rescue operation with high effort

codex rescue --model gpt-5.4-mini --effort high "investigate flaky integration test"

# Adversarial review with maximum reasoning

codex adversarial-review --effort xhigh "security audit the payment gateway"

The rescue sub-command documentation in plugins/codex/commands/rescue.md (lines 3‑20) confirms that effort flags propagate through runtime-selection semantics for all task-oriented operations.

Validation and Normalization Logic

Before sending requests to the backend, the plugin sanitizes effort values through the normalizeReasoningEffort function defined in plugins/codex/scripts/codex-companion.mjs (lines 114‑127). This helper:

1. Trims whitespace and converts input to lowercase
2. Validates against the VALID_REASONING_EFFORTS whitelist
3. Throws a descriptive error for unsupported values

function normalizeReasoningEffort(effort) {
  if (effort == null) return null;
  const normalized = String(effort).trim().toLowerCase();
  if (!VALID_REASONING_EFFORTS.has(normalized)) {
    throw new Error(`Unsupported reasoning effort "${effort}". Use one of: none, minimal, low, medium, high, xhigh.`);
  }
  return normalized;
}

This normalization ensures consistent casing and prevents invalid values from reaching the Codex app-server.

Request Building and Backend Propagation

The normalized effort value flows into the task request through the buildTaskRequest function at lines 604‑609 of codex-companion.mjs. This function constructs the payload sent to the Codex app-server turn/start endpoint:

function buildTaskRequest({ cwd, model, effort, prompt, write, resumeLast, jobId }) {
  return { cwd, model, effort, prompt, write, resumeLast, jobId };
}

The effort field in the returned object becomes part of the JSON payload transmitted to the backend. Runtime tests in tests/runtime.test.mjs (lines 766‑785) verify this propagation by asserting that fakeState.lastTurnStart.effort correctly reflects the user-specified value, confirming the backend receives the intended configuration.

Configuration File Overrides and Defaults

Projects can establish default reasoning effort levels without passing CLI flags. According to the README.md (lines 273‑278), you can set model_reasoning_effort in a .codex/config.toml file:

[model]
model_reasoning_effort = "high"

When this configuration exists and you omit the --effort flag, the plugin automatically applies the configured value. If no effort is specified via either CLI or configuration file, the plugin leaves the field unset (as noted at line 161 of README.md), allowing the Codex model to select its own default reasoning effort.

Summary

• The Codex plugin recognizes six reasoning effort levels: none, minimal, low, medium, high, and xhigh.
• Validation occurs in normalizeReasoningEffort at codex-companion.mjs lines 114‑127, which enforces the whitelist and normalizes casing.
• The --effort flag works across task, rescue, and adversarial-review commands, with values propagated via buildTaskRequest (lines 604‑609).
• Project-wide defaults can be configured in .codex/config.toml using the model_reasoning_effort key.
• Runtime tests (lines 766‑785 of runtime.test.mjs) confirm correct forwarding to the app-server turn/start endpoint.

Frequently Asked Questions

What happens if I omit the --effort flag entirely?

If you do not specify --effort and have no model_reasoning_effort configured in .codex/config.toml, the plugin leaves the effort field unset in the request payload. As implemented in the request builder at codex-companion.mjs lines 604‑609, this null value allows the Codex backend to apply its own default reasoning effort according to the model's internal configuration.

Can I set a project-wide default reasoning effort?

Yes. Create a .codex/config.toml file in your project root and include the model_reasoning_effort setting under the [model] section, as documented in the README at lines 273‑278. For example, setting model_reasoning_effort = "high" applies that level to all tasks unless explicitly overridden with the --effort flag.

What Codex plugin commands support the --effort flag?

The --effort parameter is supported by task-oriented sub-commands including task, rescue, and adversarial-review, as indicated in plugins/codex/skills/codex-cli-runtime/SKILL.md (lines 21‑35) and plugins/codex/commands/rescue.md (lines 3‑20). The flag is parsed by the generic argument handler and normalized before command execution.

How does the plugin handle invalid reasoning effort values?

The normalizeReasoningEffort function in codex-companion.mjs (lines 114‑127) validates input against the whitelist of six allowed values. If you provide an unsupported string, the function throws a clear error message listing the valid options: none, minimal, low, medium, high, and xhigh. This prevents malformed requests from reaching the Codex app-server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}