# Codex Plugin Model Aliases: How They Work and How They're Resolved

> Understand how the codex plugin model aliases work and get resolved. Discover the supported spark alias and its mapping to gpt-5.3-codex-spark.

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

---

**The `codex-plugin-cc` repository supports one model alias (`spark` → `gpt-5.3-codex-spark`) that is resolved through a simple Map lookup in the `normalizeRequestedModel` function.**

When working with the OpenAI Codex CLI plugin, you can use convenient short names instead of full model identifiers. Understanding how these aliases are defined and resolved helps you configure your workflow correctly and predict which backend model will handle your requests.

---

## Supported Model Aliases

The Codex Companion script defines model aliases in a static `Map` constant. Currently, only one alias exists:

| Alias | Resolves To |
|-------|-------------|
| `spark` | `gpt-5.3-codex-spark` |

This mapping is declared at line 72 of `plugins/codex/scripts/codex-companion.mjs`:

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

```

The Map structure allows for easy extension. Future aliases can be added as additional key-value pairs without modifying the resolution logic.

---

## Alias Resolution Process

The `normalizeRequestedModel` function handles all model string processing. Located near line 111 in `plugins/codex/scripts/codex-companion.mjs`, this function implements a four-step resolution pipeline:

### 1. Null/Empty Handling

If no `--model` argument is provided, the function returns `null`. This signals the Codex service to use its default model selection.

```javascript
// From codex-companion.mjs
if (!model) return null;

```

### 2. Normalization

The input string is trimmed of whitespace and converted to lowercase to ensure case-insensitive matching:

```javascript
const normalized = model.trim().toLowerCase();

```

### 3. Alias Lookup

The normalized string is checked against `MODEL_ALIASES`:

```javascript
return MODEL_ALIASES.get(normalized) ?? normalized;

```

### 4. Fallback

If no alias matches, the normalized original string is returned unchanged. This permits direct use of full model names like `gpt-5.4-mini` without requiring predefined aliases.

---

## Practical Usage Examples

The `--model` flag accepts both aliases and full model identifiers. Here are common patterns:

**Using the `spark` alias:**

```bash
node scripts/codex-companion.mjs task \
  --model spark \
  --effort medium \
  "Refactor this authentication module"

```

The request payload sent to Codex contains `model: "gpt-5.3-codex-spark"`.

**Using an explicit model name:**

```bash
node scripts/codex-companion.mjs task \
  --model gpt-5.4-mini \
  "Generate unit tests for the utils module"

```

The model name passes through unchanged.

**Omitting the model flag:**

```bash
node scripts/codex-companion.mjs task \
  "Create a README for this project"

```

Codex selects its default model automatically.

---

## Where Resolution Results Are Consumed

The resolved model string flows from `normalizeRequestedModel` into the core Codex client. In `plugins/codex/scripts/lib/codex.mjs`, this value populates the request payload's `model` field when constructing API calls to the Codex service.

This separation of concerns—alias definition in the CLI script, resolution in a utility function, and consumption in the HTTP client—keeps the codebase modular and testable.

---

## Summary

- **Single alias defined**: `spark` maps to `gpt-5.3-codex-spark` in `MODEL_ALIASES`
- **Resolution location**: `normalizeRequestedModel` function in `codex-companion.mjs` (line ~111)
- **Processing steps**: null check → trim/lowercase → Map lookup → fallback to original
- **Case handling**: Aliases are case-insensitive due to normalization
- **Extensibility**: New aliases require only Map entry additions

---

## Frequently Asked Questions

### What happens if I use an undefined alias?

The `normalizeRequestedModel` function returns your input unchanged (after trimming and lowercasing). If the string doesn't match a valid Codex model identifier, the API request will fail with a model-not-found error from the Codex service.

### Can I define custom aliases locally?

The current implementation hardcodes `MODEL_ALIASES` as a `const` Map. There's no configuration file or environment variable support for custom aliases. You would need to modify `plugins/codex/scripts/codex-companion.mjs` directly and rebuild the plugin.

### Why is the alias named "spark"?

The alias name refers to the **Spark** model family in the Codex product line—specialized for rapid, lightweight code assistance tasks. The full identifier `gpt-5.3-codex-spark` indicates the underlying model version and capability tier.

### Does alias resolution affect pricing or rate limits?

No. Alias resolution is purely a string substitution mechanism. The actual model identifier sent to the API determines pricing, context window, and rate limit characteristics—identical whether you use the alias or the full name.