# How the Spark Model Alias Maps to gpt-5.3-codex-spark in OpenAI Codex Plugin CC

> Discover how the spark model alias maps to gpt-5.3-codex-spark in OpenAI Codex Plugin CC. Learn about the normalizeRequestedModel function and case insensitive lookups.

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

---

**The `spark` alias maps to `gpt-5.3-codex-spark` through a hardcoded `Map` in `codex-companion.mjs`, where the `normalizeRequestedModel` function performs a case-insensitive lookup before passing the resolved identifier to the Codex runtime.**

The OpenAI Codex Plugin CC repository provides a command-line interface that accepts both full model identifiers and convenient short aliases. Understanding how these aliases resolve to concrete model names is essential for debugging CLI behavior and ensuring your requests target the correct backend. According to the source code in `openai/codex-plugin-cc`, the mapping for the `spark` alias is implemented in the companion script through a simple lookup table and normalization function.

## Where the Alias Mapping Is Defined

The canonical definition of model aliases lives in **`plugins/codex/scripts/codex-companion.mjs`** (lines 72–73). Here, a `Map` object named `MODEL_ALIASES` stores the relationship between user-friendly shortcuts and their full model identifiers:

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

```

This single entry establishes that whenever the system encounters the string `"spark"`, it should treat it as `"gpt-5.3-codex-spark"`.

## How the Normalization Logic Works

When you pass a `--model` flag to the CLI, the helper function **`normalizeRequestedModel`** (defined around lines 103–112 in the same file) processes the input. This function handles null values, trims whitespace, and converts the input to lowercase before performing the lookup:

```javascript
function normalizeRequestedModel(model) {
  if (model == null) return null;
  const normalized = String(model).trim();
  if (!normalized) return null;
  // Return the mapped value if it exists, otherwise return the original string
  return MODEL_ALIASES.get(normalized.toLowerCase()) ?? normalized;
}

```

The logic follows these steps:
1. **Null safety**: Returns `null` immediately if the input is missing or empty.
2. **String normalization**: Converts the input to a trimmed string.
3. **Case-insensitive lookup**: Converts the normalized string to lowercase and queries `MODEL_ALIASES`.
4. **Fallback**: If the alias is not found, the original string is returned unchanged, allowing full model names to pass through.

## Runtime Resolution Flow

The resolution of the `spark` alias occurs at the boundary between the CLI and the Codex runtime:

1. You execute a command with `--model spark`.
2. The parser passes `"spark"` to `normalizeRequestedModel`.
3. The function converts it to lowercase (`"spark"`) and finds the entry in `MODEL_ALIASES`.
4. The mapped value `"gpt-5.3-codex-spark"` is returned and forwarded to the Codex runtime.

This ensures that underlying API requests always use the full model identifier, even when you use the shorthand.

## CLI Usage Examples

Both of the following commands invoke the same underlying model (`gpt-5.3-codex-spark`) because the alias is automatically resolved:

```bash

# Using the full model identifier

node scripts/codex-companion.mjs task --model gpt-5.3-codex-spark "Explain recursion"

# Using the short alias

node scripts/codex-companion.mjs task --model spark "Explain recursion"

```

## Test Coverage for the Alias System

The mapping is validated by the test suite to prevent regressions. ** `tests/commands.test.mjs` ** contains assertions verifying that the CLI mentions the mapping (`spark → gpt-5.3-codex-spark`), while ** `tests/runtime.test.mjs` ** ensures the runtime receives the correctly resolved model name after alias translation.

## Summary

- ** `MODEL_ALIASES` ** is a hardcoded `Map` in `plugins/codex/scripts/codex-companion.mjs` that defines `"spark"` as an alias for `"gpt-5.3-codex-spark"`.
- ** `normalizeRequestedModel` ** performs case-insensitive lookups using `toLowerCase()`, ensuring `--model Spark` and `--model spark` resolve identically.
- If an alias is not found, the function falls back to the original input string, supporting direct use of full model identifiers.
- The mapping is exercised in `tests/commands.test.mjs` and `tests/runtime.test.mjs` to guarantee correct CLI-to-runtime translation.

## Frequently Asked Questions

### What file contains the spark model alias mapping?

The mapping is defined in `plugins/codex/scripts/codex-companion.mjs` within the `MODEL_ALIASES` Map at lines 72–73. This file also contains the `normalizeRequestedModel` function that performs the lookup.

### Is the spark alias case-sensitive?

No, the alias lookup is case-insensitive. The `normalizeRequestedModel` function converts your input to lowercase via `toLowerCase()` before checking against the `MODEL_ALIASES` map, so `--model Spark`, `--model SPARK`, and `--model spark` all resolve correctly.

### What happens if I provide an undefined alias?

If you supply an alias not present in `MODEL_ALIASES` (for example, `--model unknown`), the `normalizeRequestedModel` function returns the original string unchanged due to the nullish coalescing operator (`??`). The CLI then attempts to use that literal string as the model identifier, which typically results in a runtime error from the backend.

### How is the alias mapping tested?

The test suite verifies the mapping in two locations. `tests/commands.test.mjs` checks that the CLI documentation and help text correctly describe the `spark → gpt-5.3-codex-spark` relationship, while `tests/runtime.test.mjs` validates that the resolved model name is actually passed to the Codex runtime after alias expansion.