# Valid Reasoning Effort Values for the Codex Plugin: Validation and Usage Guide

> Discover the six valid reasoning effort values for the Codex plugin: none minimal low medium high and xhigh. Learn how to use and validate these settings for optimal performance in your projects.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: usage-guide
- Published: 2026-07-11

---

**The Codex plugin accepts exactly six reasoning effort values—`none`, `minimal`, `low`, `medium`, `high`, and `xhigh`—which are strictly validated against a whitelist defined in `codex-companion.mjs`.**

The `openai/codex-plugin-cc` repository provides a command-line interface for interacting with OpenAI's Codex models through the companion script. When configuring model behavior, developers can specify **reasoning effort values for the Codex plugin** using the `--effort` flag to control how much computational depth the model applies before generating a response. Understanding these six validated options ensures your integration fails fast with descriptive errors rather than propagating invalid parameters to the model.

## Valid Reasoning Effort Values for the Codex Plugin

The plugin recognizes a fixed set of six string literals that map to increasing levels of computational reasoning. These values are case-insensitive when provided by the user but normalized to lowercase internally.

| Value | Description |
|-------|-------------|
| **`none`** | No additional effort; the model responds immediately without extra reasoning steps. |
| **`minimal`** | A very small amount of extra computational thinking. |
| **`low`** | Low-level effort providing a modest amount of additional reasoning. |
| **`medium`** | Balanced effort between response speed and reasoning depth. |
| **`high`** | High effort enabling more thorough reasoning at the cost of increased latency. |
| **`xhigh`** | Extra-high effort representing the most exhaustive reasoning depth the plugin supports. |

These six strings constitute the complete permissible set; no other values will pass validation.

## How Reasoning Effort Validation Works in codex-companion.mjs

The validation logic resides in `plugins/codex/scripts/codex-companion.mjs` and operates through a three-stage enforcement mechanism: whitelist definition, input normalization, and membership testing.

### The Validation Whitelist

At line 71 of `codex-companion.mjs`, the source code defines an immutable `Set` containing the valid identifiers:

```javascript
const VALID_REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);

```

This constant serves as the single source of truth for permitted values throughout the application.

### Input Normalization Logic

The `normalizeReasoningEffort` function (lines 14–27) handles all user input, ensuring consistent formatting before validation:

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

```

The function coerces the input to a string, trims whitespace, converts to lowercase, and checks membership against `VALID_REASONING_EFFORTS`. If the normalized value is absent from the set, the function throws an immediate `Error` with an explicit message listing all valid options.

### Command-Line Interface Enforcement

The CLI help text explicitly documents the valid options at line 82:

```text
--effort <none|minimal|low|medium|high|xhigh>

```

This usage string provides inline documentation while the underlying validation logic enforces the constraint at runtime.

## Practical Usage Examples

### Command-Line Usage

Invoke the companion script with a valid reasoning effort value:

```bash

# Correct usage with low effort

node scripts/codex-companion.mjs task --model spark --effort low "Explain quantum entanglement"

```

Attempting to use an undefined value results in a clear validation error:

```bash

# Invalid usage throws an error

node scripts/codex-companion.mjs task --effort superhigh "Test"

# → Error: Unsupported reasoning effort "superhigh". Use one of: none, minimal, low, medium, high, xhigh.

```

### Programmatic Integration

Import the normalization function directly for server-side validation:

```javascript
import { normalizeReasoningEffort } from './plugins/codex/scripts/codex-companion.mjs';

try {
  const effort = normalizeReasoningEffort('MEDIUM'); // Returns: 'medium'
  // Pass validated `effort` into the Codex request payload
} catch (e) {
  console.error(e.message);
}

```

## Summary

- The **Codex plugin recognizes six reasoning effort values**: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
- Validation occurs in **`plugins/codex/scripts/codex-companion.mjs`** through the `VALID_REASONING_EFFORTS` Set defined at line 71.
- The **`normalizeReasoningEffort`** function (lines 14–27) normalizes input to lowercase and throws an `Error` for invalid values.
- The CLI usage string at **line 82** documents the valid options as `--effort <none|minimal|low|medium|high|xhigh>`.
- Test coverage exists in `tests/commands.test.mjs` and `tests/runtime.test.mjs` to verify validation and propagation behavior.

## Frequently Asked Questions

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

The `normalizeReasoningEffort` function throws an `Error` immediately with the message: `Unsupported reasoning effort "[value]". Use one of: none, minimal, low, medium, high, xhigh.` This prevents invalid parameters from reaching the model API.

### Is the reasoning effort parameter case-sensitive?

No. The validation logic converts all input to lowercase using `.toLowerCase()` before checking against the whitelist. Values like `"HIGH"`, `"High"`, or `"high"` all normalize to `"high"` and pass validation.

### Can I omit the reasoning effort flag entirely?

Yes. If the effort parameter is `null`, `undefined`, or an empty string after trimming, `normalizeReasoningEffort` returns `null` without throwing an error. This allows the plugin to use default model behavior when no specific effort level is requested.

### Where does the validated reasoning effort value propagate after validation?

According to the test suite in `tests/runtime.test.mjs`, the normalized effort value is attached to the turn state object, specifically accessible via `fakeState.lastTurnStart.effort`, ensuring the validated parameter flows correctly to the application server.