# Codex Plugin Reasoning Effort Levels: Supported Values and Validation Logic

> Discover the six supported reasoning effort levels for the OpenAI Codex plugin: none, minimal, low, medium, high, and xhigh. Learn about the validation logic in codex companion mjs.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-07-28

---

**The OpenAI Codex plugin supports six distinct reasoning effort levels—`none`, `minimal`, `low`, `medium`, `high`, and `xhigh`—which are strictly validated against a whitelist in `codex-companion.mjs`.**

The `openai/codex-plugin-cc` repository provides a command-line interface for controlling Codex model behavior through the `--effort` flag. This parameter dictates how much computational reasoning the model applies before generating a response, with validation enforced programmatically to prevent invalid configurations.

## Supported Reasoning Effort Levels

The plugin recognizes exactly six string identifiers that map to progressive reasoning intensities:

- **none**: No additional effort; the model responds immediately without extra thinking.
- **minimal**: A very small amount of extra reasoning.
- **low**: Low-level effort with modest additional computation.
- **medium**: Balanced reasoning that trades off between speed and depth.
- **high**: Intensive reasoning that increases latency for more thorough analysis.
- **xhigh**: Extra-high effort representing the most exhaustive reasoning mode available.

These six strings constitute the complete set of valid reasoning effort identifiers accepted by the CLI.

## How Reasoning Effort Validation Works

The validation logic is implemented in `plugins/codex/scripts/codex-companion.mjs` through a combination of whitelist definitions and normalization routines.

### Defining the Valid Set

At line 71 of `codex-companion.mjs`, the permitted values are explicitly declared as a JavaScript `Set`:

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

```

This constant serves as the authoritative whitelist against which all user inputs are compared.

### Normalization and Validation Logic

The `normalizeReasoningEffort` function (lines 14-27) handles input processing and strict 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 first normalizes the input to a lowercase string. It then checks membership in the `VALID_REASONING_EFFORTS` set. If the value is not present, an exception is thrown with a clear error message listing the allowed options.

### Command-Line Integration

The CLI help text explicitly documents the allowed values. Line 82 defines the usage pattern as:

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

```

This ensures users discover valid options through built-in documentation before execution.

## Practical Usage Examples

Correct CLI invocation:

```bash
node scripts/codex-companion.mjs task --model spark --effort low "Explain why the sky is blue"

```

Invalid usage triggers an immediate error:

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

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

```

Programmatic usage in JavaScript:

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

try {
  const effort = normalizeReasoningEffort('MEDIUM'); // Returns 'medium'
  // Use normalized value in Codex request payload
} catch (e) {
  console.error(e.message);
}

```

## Summary

- The Codex plugin accepts exactly six reasoning effort levels: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
- Validation occurs in `normalizeReasoningEffort` within `plugins/codex/scripts/codex-companion.mjs` using the `VALID_REASONING_EFFORTS` whitelist.
- Invalid values trigger descriptive errors listing all permitted options.
- The parameter is case-insensitive after normalization but must match one of the six defined strings exactly.
- Test coverage exists in `tests/commands.test.mjs` and `tests/runtime.test.mjs`.

## Frequently Asked Questions

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

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

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

No. The validation logic converts input to lowercase via `String(effort).trim().toLowerCase()`, so "HIGH", "High", and "high" are all valid and normalize to `"high"`.

### Which files contain tests for reasoning effort validation?

The test suite validates this behavior in `tests/commands.test.mjs` (asserting help text and validation errors) and `tests/runtime.test.mjs` (verifying propagation to `fakeState.lastTurnStart.effort`).

### What is the default reasoning effort if I don't specify --effort?

When `effort` is `null` or an empty string, `normalizeReasoningEffort` returns `null`, indicating no specific reasoning effort is applied and the system uses its default behavior.