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

> Discover how the Codex plugin implements model aliasing with a lookup table and normalization function. Learn to map 'spark' to specific backend models.

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

---

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

```javascript
// 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.

```bash

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