How Codex Models and Reasoning Efforts Are Normalized in openai/codex-plugin-cc

The Codex plugin normalizes both the model identifier supplied by the user and the reasoning-effort flag before any interaction with the Codex service, ensuring a consistent internal representation and preventing accidental typos.

The openai/codex-plugin-cc repository provides a CLI plugin that interfaces with OpenAI's Codex service. Before transmitting requests to the backend, the plugin transforms raw user input into canonical forms through dedicated normalization utilities. This article examines how Codex models and reasoning efforts are normalized within the codex-companion.mjs script to guarantee API compatibility and user-friendly interfaces.

Model Normalization Pipeline

The normalizeRequestedModel function in plugins/codex/scripts/codex-companion.mjs (lines 103–112) handles the transformation of model identifiers through a four-step process:

1. Null Safety Check

If the input is null or undefined, the function returns null immediately. This signals downstream logic to select a default model rather than proceeding with an empty string.

2. String Coercion and Trimming

The raw value is converted to a string and stripped of surrounding whitespace using String(model).trim(). This eliminates accidental leading or trailing spaces from user input.

3. Case-Insensitive Alias Resolution

The normalized string is matched against MODEL_ALIASES (defined at line 72), a Map containing friendly shortcuts. For example, the alias spark resolves to gpt-5.3-codex-spark. The lookup uses normalized.toLowerCase() to ensure case-insensitive matching, allowing users to type Spark, SPARK, or spark interchangeably.

4. Fallback Pass-Through

If no alias matches, the trimmed string returns unchanged. This preserves explicit full model names provided by advanced users while still benefiting from whitespace removal.

Reasoning-Effort Normalization

The companion function normalizeReasoningEffort (lines 114–128) validates effort levels through strict enumeration against known API values:

1. Null Handling

Returns null when the flag is omitted, signaling the use of server-side defaults rather than client-specified effort levels.

2. String Sanitization

Input undergoes String(effort).trim().toLowerCase() to eliminate case and whitespace variations, ensuring consistent comparison regardless of user formatting.

3. Validation Against Allowed Values

The sanitized token must exist within VALID_REASONING_EFFORTS (line 71), a Set containing the exact strings: none, minimal, low, medium, high, and xhigh. This whitelist approach prevents invalid API parameters from reaching the Codex service.

4. Explicit Error Reporting

Invalid values trigger an informative error listing all accepted tokens. This fail-fast mechanism surfaces misuse immediately, preventing wasted network requests and ambiguous API calls.

Implementation Details in Source Code

According to the source code in openai/codex-plugin-cc, both normalization utilities reside in plugins/codex/scripts/codex-companion.mjs:

• normalizeRequestedModel: Lines 103–112 implement the alias mapping logic using MODEL_ALIASES.
• normalizeReasoningEffort: Lines 114–128 enforce the reasoning-effort constraints against VALID_REASONING_EFFORTS.
• MODEL_ALIASES: Line 72 defines the Map connecting user shortcuts to canonical model names.
• VALID_REASONING_EFFORTS: Line 71 declares the Set of permissible effort levels.

Practical Usage Examples

The following examples demonstrate how to use these normalization helpers in practice:

// Normalizing a model alias to canonical form
const modelInput = "  Spark  ";
const normalizedModel = normalizeRequestedModel(modelInput);
// Result: "gpt-5.3-codex-spark"
console.log(normalizedModel);

// Normalizing mixed-case reasoning effort
const effortInput = "Medium";
const normalizedEffort = normalizeReasoningEffort(effortInput);
// Result: "medium"
console.log(normalizedEffort);

// Integration within a command handler
function runRescueCommand(opts) {
  const model = normalizeRequestedModel(opts.model);
  const effort = normalizeReasoningEffort(opts.effort);
  
  // Sanitized values ready for Codex API transmission
  codexClient.runRescue({ model, effort, ...opts });
}

Why Normalization Matters

• Consistency: Downstream components receive canonical strings (gpt-5.3-codex-spark) rather than ambiguous aliases (spark), eliminating divergent code paths and conditional logic scattered throughout the codebase.
• User Experience: CLI users can type intuitive shortcuts or mixed-case values (Medium) without memorizing exact API requirements or worrying about whitespace.
• Fail-Fast Validation: Invalid reasoning efforts surface immediately through descriptive errors citing the valid set (none, minimal, low, medium, high, xhigh), preventing runtime API errors and reducing debugging time.

Summary

• The normalizeRequestedModel function in plugins/codex/scripts/codex-companion.mjs converts user-friendly aliases to full model names using a case-insensitive Map lookup against MODEL_ALIASES (line 72).
• The normalizeReasoningEffort function validates input against a strict Set of allowed values (none, minimal, low, medium, high, xhigh), throwing descriptive errors for invalid tokens.
• Both functions trim whitespace, handle null values gracefully, and ensure the Codex plugin transmits only sanitized, API-compliant data.
• Line-specific implementations reside at lines 103–112 and 114–128 of codex-companion.mjs, with constants defined at lines 71–72.

Frequently Asked Questions

What happens if I provide an invalid reasoning effort value?

The normalizeReasoningEffort function throws an informative error listing all valid options (none, minimal, low, medium, high, xhigh) before any network request occurs. This immediate feedback allows users to correct typos without waiting for an API error response.

Can I use uppercase letters when specifying a model alias?

Yes. The normalization pipeline converts input to lowercase via toLowerCase() before checking MODEL_ALIASES, so SPARK, Spark, and spark all correctly resolve to gpt-5.3-codex-spark according to the implementation at lines 103–112.

Where are the normalization functions located in the repository?

Both normalizeRequestedModel and normalizeReasoningEffort are implemented in plugins/codex/scripts/codex-companion.mjs, specifically at lines 103–112 and 114–128 respectively, with their associated constants defined at lines 71–72.

What is the default behavior if I omit the model or reasoning effort parameters?

When normalizeRequestedModel receives null or undefined, it returns null, prompting the plugin to select a default model. Similarly, normalizeReasoningEffort returns null for omitted efforts, typically resulting in the Codex API applying its own server-side defaults.

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