Codex Plugin Reasoning Effort Levels: Supported Values and Validation Logic

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:

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:

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:

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

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

Invalid usage triggers an immediate 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 usage in 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.

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