# How the Codex Plugin Handles Model Aliases Like `spark`

> Discover how the Codex plugin uses a lookup map in codex companion mjs to resolve model aliases like spark to full identifiers, ensuring command consistency and catalog integrity.

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

---

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

```bash

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