# How the Codex Plugin Handles Model Selection and the `spark` Alias Mapping

> Discover how the Codex plugin handles model selection and the spark alias mapping. Learn how user input is normalized before API forwarding.

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

---

**The Codex plugin resolves the `spark` alias to `gpt-5.3-codex-spark` using a hardcoded `Map` in `codex-companion.mjs`, normalizing user input before forwarding it to the API.**

The openai/codex-plugin-cc repository provides a CLI companion that simplifies model selection for Codex operations. Understanding how model selection works—including the shorthand `spark` alias—helps developers use the tool efficiently while ensuring the correct model reaches the OpenAI API.

## The Model Alias System

The plugin implements a lightweight alias resolution layer that sits between user input and API calls. This design prioritizes memorability for users while maintaining precision for backend operations.

### The MODEL_ALIASES Map

At the core of the system is a `Map` named `MODEL_ALIASES` defined in `plugins/codex/scripts/codex-companion.mjs` (lines 72-74). This map contains a single entry:

```javascript
const MODEL_ALIASES = new Map([["spark", "gpt-5.3-codex-spark"]]);

```

The key `"spark"` maps to the full model identifier `"gpt-5.3-codex-spark"`. This hardcoded mapping ensures consistent resolution across all plugin invocations.

### Normalization Logic

Before arguments reach the underlying `task` command, the plugin normalizes the `--model` value. In `plugins/codex/scripts/codex-companion.mjs` (lines 80-82), the code checks whether the supplied model argument exists as a key in `MODEL_ALIASES`. When a match is found, the map's value overwrites the original user input.

```javascript
function normalizeModelArg(arg) {
  // If the user passed "spark", replace it with the full model name
  return MODEL_ALIASES.get(arg) ?? arg;
}

// Example usage
const userModel = "spark";
const actualModel = normalizeModelArg(userModel); // => "gpt-5.3-codex-spark"

```

The nullish coalescing operator (`??`) ensures that unrecognized model names pass through unchanged, allowing direct use of full model identifiers when desired.

## CLI Usage and Propagation

Once normalized, the resolved model name flows through the command chain to the OpenAI API.

### Command-Line Examples

Users can invoke the plugin with either the alias or full name:

```bash

# Using the short alias

codex:rescue --model spark fix the broken test

# The plugin internally rewrites this to:

#   --model gpt-5.3-codex-spark

```

Both forms ultimately trigger the same API call with `gpt-5.3-codex-spark` as the model parameter.

### Propagation Chain

The normalized `--model` argument passes to the `task` sub-command, which constructs the final API request. This separation of concerns—user-friendly aliases at the CLI layer, exact identifiers at the API layer—prevents model name mismatches while preserving flexibility.

## Documentation and User Discovery

The alias behavior is documented across multiple files to ensure discoverability.

| File | Documentation Role |
|------|------------------|
| `plugins/codex/scripts/codex-companion.mjs` | Implements `MODEL_ALIASES` and normalization logic (lines 72-82) |
| [`README.md`](https://github.com/openai/codex-plugin-cc/blob/main/README.md) (Model selection section) | Explicitly states that `spark` maps to `gpt-5.3-codex-spark` (lines 149-162) |
| [`plugins/codex/skills/codex-cli-runtime/SKILL.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/skills/codex-cli-runtime/SKILL.md) | Lists the alias in skill definitions (lines 23-29) |
| [`plugins/codex/commands/rescue.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md) | Shows `--model` flag help mentioning the alias (lines 46-48) |

This redundant documentation ensures users encounter the alias behavior in help text, README, and skill metadata alike.

## Extending the Alias System

The `Map`-based implementation in `codex-companion.mjs` supports additional aliases with minimal changes. To add a new alias, a maintainer would append another entry to the `MODEL_ALIASES` constructor array:

```javascript
const MODEL_ALIASES = new Map([
  ["spark", "gpt-5.3-codex-spark"],
  ["legacy", "gpt-4-codex"] // hypothetical addition
]);

```

The normalization function requires no modification due to its generic lookup pattern.

## Summary

- **Alias resolution** happens in `plugins/codex/scripts/codex-companion.mjs` via the `MODEL_ALIASES` Map
- **The `spark` alias** unconditionally maps to `gpt-5.3-codex-spark` before API calls
- **Normalization preserves** unrecognized model names, allowing direct use of full identifiers
- **Documentation** in README.md, SKILL.md, and command help ensures user awareness
- **Design pattern** separates user-friendly CLI input from precise API requirements

## Frequently Asked Questions

### What happens if I use a model name that isn't in the alias map?

The plugin passes your input unchanged to the API. The `normalizeModelArg` function uses `MODEL_ALIASES.get(arg) ?? arg`, which returns the original string when no alias matches. You can use any valid OpenAI model identifier directly.

### Can I add custom aliases locally?

The current implementation hardcodes aliases in `codex-companion.mjs`. To add custom mappings, you would need to modify the source file and rebuild the plugin. There is no runtime configuration file for aliases in the current version.

### Is the `spark` alias available in all Codex plugin commands?

Yes. The normalization logic runs in the companion script before dispatch to sub-commands, so any CLI invocation that accepts `--model` will resolve the `spark` alias consistently.