# How the Codex Plugin Supports Different Reasoning Effort Levels

> Discover how the Codex plugin utilizes six effort levels from none to xhigh to control model reasoning intensity. Learn to leverage the --effort flag for tailored AI responses.

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

---

**The Codex plugin controls model reasoning intensity through six validated effort levels (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`) that are normalized from command-line input and forwarded to the Codex app-server via the `--effort` flag.**

The openai/codex-plugin-cc repository provides a command-line interface for interacting with OpenAI's Codex model, including granular control over how much computational "thinking" the model applies to each task. Understanding how the Codex plugin handles different reasoning effort levels helps developers optimize the trade-off between response quality and latency for various coding workflows.

## Valid Reasoning Effort Levels in the Source Code

In `plugins/codex/scripts/codex-companion.mjs` at line 71, the plugin defines a whitelist of valid reasoning effort values. These levels range from `none` (no reasoning effort) to `xhigh` (maximum reasoning effort), allowing precise tuning of model behavior.

The complete set of supported values includes:
- `none`
- `minimal`
- `low`
- `medium`
- `high`
- `xhigh`

### Input Validation and Normalization

The `normalizeReasoningEffort` function (lines 114-127 in `codex-companion.mjs`) handles input sanitization by trimming whitespace, converting to lowercase, and validating against the whitelist. If an unsupported value is provided, the function throws a descriptive error message listing all valid options.

## Command-Line Interface for Reasoning Effort Control

Users specify their desired reasoning level using the `--effort` flag on task-related subcommands such as `task`, `rescue`, or `adversarial-review`. The argument parser captures this value before the request is constructed.

Example commands:

```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"

```

## Building and Forwarding the Task Request

Inside `buildTaskRequest` (lines 604-609 in `codex-companion.mjs`), the normalized effort value is included in the request object sent to the Codex app-server. The function signature accepts an `effort` parameter alongside other task metadata like `cwd`, `model`, and `prompt`.

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

```

The effort field is then forwarded to the app-server's turn/start endpoint, as verified in `tests/runtime.test.mjs` (lines 766-785). The test suite confirms that `fakeState.lastTurnStart.effort` correctly receives the user-specified value, ensuring the backend actually processes the reasoning level.

## Default Behavior and Configuration File Overrides

When the `--effort` flag is omitted, the plugin leaves the field unset, allowing the Codex model to apply its own default reasoning effort level. This behavior is documented in the README at line 161.

Projects can establish persistent defaults by setting `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"

```

As documented in lines 273-278 of the README, this configuration value is automatically applied when no explicit `--effort` flag is provided on the command line.

## Summary

- The Codex plugin supports six validated reasoning effort levels: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
- Input validation occurs in `normalizeReasoningEffort` within `plugins/codex/scripts/codex-companion.mjs`, which normalizes case and validates against a whitelist.
- Users control effort via the `--effort` flag on task subcommands.
- The `buildTaskRequest` function incorporates the effort value into the payload sent to the Codex app-server.
- Default behavior allows the model to choose its own effort level when unspecified, with optional overrides available through [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml).

## Frequently Asked Questions

### What reasoning effort levels does the Codex plugin support?

The plugin supports six distinct levels: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. These values are defined in a whitelist at line 71 of `plugins/codex/scripts/codex-companion.mjs` and represent a spectrum from no reasoning effort to maximum computational investment.

### How do I set a default reasoning effort for all tasks in a project?

Create a [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) file in your project root and set the `model_reasoning_effort` key under the `[model]` section. For example: `model_reasoning_effort = "high"`. According to the README at lines 273-278, this configuration applies automatically when you run commands without the `--effort` flag.

### What happens if I provide an invalid reasoning effort value?

The `normalizeReasoningEffort` function throws an error with a clear message listing all valid options. Located at lines 114-127 in `codex-companion.mjs`, this validation ensures only supported values reach the Codex backend, preventing malformed requests.

### Does the reasoning effort setting affect all Codex plugin commands?

The `--effort` flag is available on task-oriented subcommands including `task`, `rescue`, and `adversarial-review`. The value is normalized and forwarded to the app-server for any command that builds a task request via `buildTaskRequest`, as confirmed by the runtime tests at lines 766-785 in `tests/runtime.test.mjs`.