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

> Discover how the openai/codex-plugin-cc normalizes Codex models and reasoning efforts for consistent internal representation and to prevent typos. Learn more now!

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-10

---

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

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

```

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

```

```javascript
// 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.