Model Aliases and Reasoning Effort Options in the OpenAI Codex Plugin

The OpenAI Codex plugin supports six reasoning effort levels (none to xhigh) and one model alias (spark → gpt-5.3-codex-spark), validated via VALID_REASONING_EFFORTS and MODEL_ALIASES in codex-companion.mjs.

The openai/codex-plugin-cc repository provides the reference implementation for integrating Codex into development environments. Understanding the available model aliases and reasoning effort options helps you control response latency and quality when invoking the Codex CLI or programmatic API. These configurations are validated against strict Sets and Maps defined in the companion script.

Supported Reasoning Effort Levels

The plugin defines acceptable reasoning values in a Set named VALID_REASONING_EFFORTS located in plugins/codex/scripts/codex-companion.mjs. This validation ensures only six specific string values reach the underlying Codex API.

The supported effort levels are:

• none – No additional reasoning; optimizes for response speed
• minimal – Negligible computational overhead
• low – Modest reasoning suitable for straightforward tasks
• medium – Default effort applied when the user omits the flag
• high – Extensive reasoning for complex logic requirements
• xhigh – Maximum reasoning depth for challenging prompts

When you omit the effort parameter, Codex defaults to medium reasoning with the standard gpt-5.4 model configuration.

Model Alias Mapping

Instead of entering full model identifiers, you can use shorthand aliases maintained in the MODEL_ALIASES Map. Currently, the plugin supports a single alias:

• spark → expands to gpt-5.3-codex-spark

The helper function normalizeRequestedModel consults this Map in plugins/codex/scripts/codex-companion.mjs. If your input matches a defined alias, the function returns the full model string; otherwise, it passes your input through unchanged to the API.

Configuration Examples

Command Line Interface

Pass --model and --effort flags to the companion script:

node scripts/codex-companion.mjs task \
  --model spark \
  --effort low \
  "Explain optimistic concurrency control"

This expands spark to gpt-5.3-codex-spark and sets the reasoning effort to low.

Programmatic API

When building requests via buildTaskRequest in plugins/codex/scripts/lib/codex.mjs:

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

const request = buildTaskRequest({
  cwd: process.cwd(),
  model: "spark",               // Normalized to gpt-5.3-codex-spark
  effort: "high",               // Must be in VALID_REASONING_EFFORTS
  prompt: "Refactor authentication logic",
  write: false,
  resumeLast: false,
  jobId: undefined,
});

Error Handling

Invalid effort values trigger errors via normalizeReasoningEffort:

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

Implementation Details

The validation and normalization logic resides in these key files:

• plugins/codex/scripts/codex-companion.mjs – Defines VALID_REASONING_EFFORTS and MODEL_ALIASES; exports normalizeRequestedModel and normalizeReasoningEffort
• plugins/codex/scripts/lib/codex.mjs – Implements buildTaskRequest which consumes normalized values
• plugins/codex/scripts/lib/args.mjs – Parses --model and --effort CLI arguments

Summary

• The Codex plugin recognizes six discrete reasoning efforts: none, minimal, low, medium, high, and xhigh
• A single model alias maps spark to gpt-5.3-codex-spark via the MODEL_ALIASES Map
• Both CLI and programmatic interfaces validate inputs through normalizeReasoningEffort and normalizeRequestedModel
• Omitting these options triggers defaults: typically gpt-5.4 with medium reasoning effort

Frequently Asked Questions

What happens if I specify an invalid reasoning effort?

The normalizeReasoningEffort function throws a descriptive error enumerating all valid options from VALID_REASONING_EFFORTS. The message explicitly lists: none, minimal, low, medium, high, and xhigh.

Can I add custom model aliases to the Codex plugin?

The MODEL_ALIASES Map in codex-companion.mjs currently hardcodes only the spark entry. To support additional aliases, you must modify the source Map directly; otherwise, unknown strings pass through unchanged to the underlying model API.

Does the reasoning effort affect token usage or billing?

Higher effort levels like high and xhigh typically increase processing time and may consume additional tokens during internal reasoning steps. The plugin documentation recommends leaving both flags unset unless you explicitly require control over these parameters.

Which model and effort level runs by default?

When you omit both the --model and --effort flags, Codex selects its own defaults—typically gpt-5.4 with medium reasoning effort—unless overridden by server-side configuration.

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