Codex Reasoning Effort Levels and Model Aliases: Complete Reference for the OpenAI Plugin

The Codex plugin supports six reasoning effort levels (none, minimal, low, medium, high, xhigh) and one model alias (spark → gpt-5.3-codex-spark), validated against fixed Sets in the companion script.

The openai/codex-plugin-cc repository provides the official command-line interface and programmatic API for controlling Codex execution. Understanding the supported reasoning effort levels and model aliases is essential for optimizing the trade-off between response quality and latency in your development workflow.

Supported Reasoning Effort Levels

The plugin defines a strict validation set called VALID_REASONING_EFFORTS that constrains how much computational reasoning the model applies to a task.

The Six Valid Reasoning Effort Values

In plugins/codex/scripts/codex-companion.mjs, the valid options are declared as:

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

Each value controls the specific trade-off between response speed and thoroughness:

• none: No extra reasoning time; the model responds as quickly as possible
• minimal: Very little additional computation
• low: A modest amount of extra reasoning
• medium: The default amount used when no value is specified
• high: More thorough reasoning for complex prompts
• xhigh: The maximum level of reasoning effort available

Any value outside this set triggers an error when processed by normalizeReasoningEffort.

Model Aliases in Codex

Rather than requiring full model identifiers, the plugin supports shorthand aliases through the MODEL_ALIASES Map.

The Spark Alias

The current alias mapping is defined in plugins/codex/scripts/codex-companion.mjs:

const MODEL_ALIASES = new Map([["spark", "gpt-5.3-codex-spark"]]);

When you pass --model spark to the CLI or include model: "spark" in the programmatic API, the helper function normalizeRequestedModel expands this to the full identifier gpt-5.3-codex-spark. Any string not matching a known alias passes through unchanged to the underlying service.

Normalization and Validation Logic

The plugin validates inputs through two key functions before constructing requests.

Input Normalization Functions

• normalizeRequestedModel: Consults MODEL_ALIASES to expand shorthand names; returns unmodified strings for unrecognized values
• normalizeReasoningEffort: Checks against VALID_REASONING_EFFORTS; throws an error for unsupported values

These functions are called internally by buildTaskRequest in plugins/codex/scripts/lib/codex.mjs, ensuring all requests meet the schema requirements before reaching the app server.

Practical Usage Examples

CLI Usage with codex-companion.mjs

Execute tasks with specific reasoning levels and model aliases directly from the command line:

node scripts/codex-companion.mjs task \
  --model spark \
  --effort high \
  "Refactor this function to use async/await"

This command normalizes spark to gpt-5.3-codex-spark and sets the reasoning effort to high before sending the request to the app server.

Programmatic API Integration

Import buildTaskRequest to construct valid requests within your own plugins:

import { buildTaskRequest } from "./plugins/codex/scripts/lib/codex.mjs";

const request = buildTaskRequest({
  cwd: process.cwd(),
  model: "spark",        // Expands to gpt-5.3-codex-spark
  effort: "low",         // Must be in VALID_REASONING_EFFORTS
  prompt: "Optimize database queries",
  write: false,
  resumeLast: false,
  jobId: undefined,
});

Handling Invalid Reasoning Efforts

Attempting to use an unsupported effort level throws a descriptive error:

try {
  const effort = normalizeReasoningEffort("ultra");
} catch (e) {
  console.error(e.message);
  // Output: "Unsupported reasoning effort \"ultra\". Use one of: none, minimal, low, medium, high, xhigh."
}

Summary

• The VALID_REASONING_EFFORTS Set in plugins/codex/scripts/codex-companion.mjs restricts inputs to six specific values: none, minimal, low, medium, high, and xhigh
• The MODEL_ALIASES Map currently supports only one alias: spark → gpt-5.3-codex-spark
• Functions normalizeRequestedModel and normalizeReasoningEffort validate inputs before request construction via buildTaskRequest
• When omitted, Codex defaults to gpt-5.4 with medium reasoning effort
• Invalid effort values throw explicit errors listing all supported options

Frequently Asked Questions

What happens if I don't specify a reasoning effort or model?

When you omit the --effort or --model flags, the plugin leaves both values unset. According to the implementation in openai/codex-plugin-cc, the underlying Codex service applies its own defaults: typically gpt-5.4 for the model and medium for the reasoning effort level.

Can I add custom model aliases to the plugin?

The MODEL_ALIASES Map is hardcoded in plugins/codex/scripts/codex-companion.mjs with only the spark entry. To add custom aliases, you would need to modify the source code and add entries to the Map initialization before the plugin loads.

What is the difference between high and xhigh reasoning effort?

Both values increase processing time beyond the default, but xhigh represents the maximum reasoning budget available in the Codex plugin, while high provides substantial analysis without reaching the upper limit. Use xhigh for complex architectural decisions and high for detailed code reviews.

How do I validate reasoning effort before sending a request?

You can import and call normalizeReasoningEffort from the companion script utilities to pre-validate values. This function checks against VALID_REASONING_EFFORTS and throws an error with the complete list of valid options if the input is invalid.

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