How the Codex Plugin Handles Model Aliases Like `spark`

The Codex plugin resolves short aliases such as spark to full model identifiers using a centralized lookup map in codex-companion.mjs, enabling concise CLI commands while maintaining internal consistency with the full model catalog.

The openai/codex-plugin-cc repository provides a command-line interface for running Codex tasks. When users specify models via the --model flag, the plugin transparently converts shorthand aliases to complete model names, streamlining the developer workflow without requiring memorization of lengthy identifiers.

Alias Resolution Architecture in codex-companion.mjs

The core logic for expanding aliases resides in plugins/codex/scripts/codex-companion.mjs, which implements a two-stage normalization pipeline.

The MODEL_ALIASES Registry

Located at lines 72-73 in plugins/codex/scripts/codex-companion.mjs, the MODEL_ALIASES Map stores the supported shortcuts. Currently, it maps the string "spark" to the full identifier "gpt-5.3-codex-spark" according to the source code.

The normalizeRequestedModel Normalization Routine

The normalizeRequestedModel function (lines 103-112) processes the raw --model argument. It trims and lower-cases the input, checks against the MODEL_ALIASES map, and returns the mapped full model name if found. If no alias matches, the function returns the original string unchanged, allowing direct use of full model identifiers that are not in the alias table.

Using Model Aliases in the CLI

Both full model names and aliases produce identical behavior at runtime.

Command-Line Examples

# Using the full model identifier

node plugins/codex/scripts/codex-companion.mjs task --model gpt-5.3-codex-spark "Explain the code"

# Using the spark alias

node plugins/codex/scripts/codex-companion.mjs task --model spark "Explain the code"

Internally, the second command expands to the first before reaching the Codex runtime via runAppServerTurn or runAppServerReview.

Integration with the Argument Parsing Pipeline

The resolution chain involves three key files that ensure backward-compatible CLI usage.

From args.mjs to codex.mjs

First, plugins/codex/scripts/lib/args.mjs parses the --model flag and passes the raw value to normalizeRequestedModel. Then, the normalized result flows to plugins/codex/scripts/lib/codex.mjs, which launches the actual Codex jobs using the resolved identifier. This ensures that downstream components always receive canonical model names while users enjoy the convenience of short aliases.

Summary

• The MODEL_ALIASES Map in plugins/codex/scripts/codex-companion.mjs (lines 72-73) defines supported shortcuts like spark → gpt-5.3-codex-spark.
• The normalizeRequestedModel function (lines 103-112) handles case-insensitive lookup and fallback to literal strings.
• Users can invoke --model spark interchangeably with --model gpt-5.3-codex-spark, with expansion occurring before the runtime receives the value.
• The alias system bridges user-friendly CLI inputs with the full model catalog required by the Codex runtime.

Frequently Asked Questions

Where are model aliases defined in the Codex plugin?

Aliases are defined in the MODEL_ALIASES Map located at lines 72-73 of plugins/codex/scripts/codex-companion.mjs. As implemented in openai/codex-plugin-cc, this map currently includes the spark alias mapping to gpt-5.3-codex-spark.

What happens if I provide an unknown alias?

If the supplied value does not match any key in MODEL_ALIASES, the normalizeRequestedModel function returns the original string unchanged. The Codex runtime will then attempt to use that literal value as the model identifier, which may result in an error if the model does not exist in the catalog.

Is the alias lookup case-sensitive?

No. The normalizeRequestedModel function converts the input to lower-case before checking against the alias map, so --model Spark, --model SPARK, and --model spark are all valid and resolve identically according to the source code implementation.

Can I add custom model aliases?

The source code uses a hard-coded Map, so adding custom aliases requires modifying the MODEL_ALIASES definition in plugins/codex/scripts/codex-companion.mjs and restarting the CLI. There is currently no external configuration file for alias definitions.

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