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

> Explore the six reasoning effort levels for the Codex plugin: none, minimal, low, medium, high, and xhigh. Learn how to configure them using CLI flags or the config file.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-16

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/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.

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/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

```javascript
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:

```javascript
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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file:

```toml
[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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-cli-runtime/SKILL.md) (lines 21‑35) and [`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/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.