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

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:

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:

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:

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

# 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:

# 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:

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.

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