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

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:

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:

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:

# 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.

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