How the Codex Plugin Implements Model Aliasing: Mapping 'spark' to 'gpt-5.3-codex-spark'

The Codex plugin implements model aliasing by defining a lookup table (MODEL_ALIASES) and normalizing user input through a normalizeRequestedModel function before sending requests to the backend.

The openai/codex-plugin-cc repository provides a command-line interface for interacting with OpenAI Codex models. Understanding how the plugin handles model aliasing reveals how short, user-friendly names like spark are transparently converted to full model identifiers such as gpt-5.3-codex-spark before API requests are dispatched.

The Alias Table Structure

The foundation of the aliasing system is a static Map named MODEL_ALIASES defined in plugins/codex/scripts/codex-companion.mjs. This data structure stores the canonical mappings between user-facing shortcuts and their corresponding full model names.

According to the source code, the map is initialized near the top of the companion script and currently contains the entry mapping "spark" to "gpt-5.3-codex-spark" at line 72. This centralized definition ensures that all alias resolutions reference a single source of truth, making maintenance and future additions straightforward.

The Normalization Helper Function

The core logic for resolving aliases lives in the normalizeRequestedModel function, implemented between lines 103-112 in codex-companion.mjs. This utility performs a case-insensitive lookup against MODEL_ALIASES and returns the full model identifier when a match is found.

If the requested model name does not exist in the alias table, the function falls back to returning the original input unchanged. This design allows power users to specify full model names directly while still supporting convenient shortcuts for common configurations.

// Conceptual implementation based on lines 103-112
function normalizeRequestedModel(requestedModel) {
  const normalized = MODEL_ALIASES.get(requestedModel.toLowerCase());
  return normalized || requestedModel;
}

Integration with the Task Command

The aliasing mechanism is applied during the execution of the task command. When parsing CLI arguments, the raw --model value (accessible as options.model) is passed through normalizeRequestedModel before being incorporated into the API request payload.

This integration occurs between lines 73-96 in codex-companion.mjs, where the normalized model identifier is assigned to the model variable and subsequently included in the request sent to the Codex backend. This ensures that regardless of whether the user types --model spark or --model gpt-5.3-codex-spark, the backend receives the canonical full model name.

# User-friendly alias usage

codex:task --model spark "Explain the algorithm"

# Behind the scenes transformation:

# 1. options.model receives "spark"

# 2. normalizeRequestedModel("spark") returns "gpt-5.3-codex-spark"

# 3. Request payload contains: { model: "gpt-5.3-codex-spark" }

Verification Through Testing

The alias resolution logic is validated by the plugin's test suite to prevent regression. The tests/runtime.test.mjs file contains assertions verifying that aliases resolve to their full model names during actual execution, while tests/commands.test.mjs ensures that CLI help documentation accurately reflects available aliases.

These tests confirm that the mapping from spark to gpt-5.3-codex-spark functions correctly across different invocation contexts and that the normalization helper handles edge cases such as case sensitivity properly.

Summary

• MODEL_ALIASES serves as the centralized registry for model mappings, currently defining "spark" → "gpt-5.3-codex-spark" in codex-companion.mjs at line 72.
• normalizeRequestedModel handles case-insensitive lookups and fallback logic between lines 103-112.
• The task command applies normalization to --model arguments during parsing (lines 73-96) before API transmission.
• The test suite in tests/runtime.test.mjs and tests/commands.test.mjs validates alias resolution and documentation accuracy.

Frequently Asked Questions

How do I add a custom model alias to the Codex plugin?

To add a custom alias, modify the MODEL_ALIASES Map in plugins/codex/scripts/codex-companion.mjs at line 72. Insert a new key-value pair where the key is your desired short name and the value is the full model identifier. You should also add corresponding test cases in tests/runtime.test.mjs to verify the new mapping resolves correctly during execution.

Does the Codex plugin support case-insensitive model aliases?

Yes, the normalizeRequestedModel function performs case-insensitive lookups against the MODEL_ALIASES Map. This means --model Spark, --model SPARK, and --model spark all resolve to gpt-5.3-codex-spark before the request is sent to the backend.

What happens if I specify a model name that is not in the alias table?

If the requested model name is not found in MODEL_ALIASES, the normalizeRequestedModel function returns the original input unchanged. This allows direct usage of full model identifiers or experimental model names that have not yet been added to the alias registry.

Where is the model alias resolution tested in the codebase?

The resolution logic is tested in two primary locations: tests/runtime.test.mjs verifies that aliases correctly map to full model names during actual command execution, while tests/commands.test.mjs ensures that the CLI help text and documentation properly describe available aliases to users.

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