# How the Codex Plugin Selects Which Model to Use: A Complete Guide

> Understand how the Codex plugin selects an LLM model. Learn about parsing flags, alias normalization, and default model fallback for openai/codex-plugin-cc.

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

---

**The Codex plugin determines which LLM model to use by parsing a user-provided `--model` flag, normalizing known aliases like "spark" to canonical names, and falling back to the Codex service's default (`gpt-5.4`) when no model is specified.**

The OpenAI Codex plugin for the CC ecosystem provides a flexible mechanism for model selection that balances user control with sensible defaults. Rather than hard-coding a specific model, the plugin implements a resolution pipeline that processes command-line arguments, resolves aliases, and propagates the final value to the underlying Codex service. Understanding how the Codex plugin selects which model to use helps developers optimize performance and cost for different coding tasks.

## Command-Line Model Selection

The primary entry point for model selection is the `--model` flag available across all runner commands. In `plugins/codex/scripts/codex-companion.mjs`, the CLI accepts this flag for commands including `task`, `review`, and `adversarial-review`.

The argument parser `parseArgs` (imported from `plugins/codex/scripts/lib/args.mjs`) extracts the raw model string from the command line.

```bash
node scripts/codex-companion.mjs task --model spark "Write a function that flattens a nested array"

```

## Alias Normalization and Resolution

Once parsed, the raw model string undergoes normalization in `plugins/codex/scripts/codex-companion.mjs` (lines 72-112). The `normalizeRequestedModel` function checks the value against a predefined alias map:

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

```

If the supplied string matches an alias, the function returns the canonical model name. If no alias exists, it returns the original string unchanged. When the `--model` flag is omitted entirely, the function returns `null`.

This design allows users to use convenient shorthand while maintaining flexibility to specify full model names directly.

## Default Model Behavior

When `normalizeRequestedModel` returns `null` (indicating no model was specified), the system delegates to Codex's internal defaults. The helper functions `runAppServerTurn` and `runAppServerReview` in `plugins/codex/scripts/lib/codex.mjs` handle this case by allowing the Codex service to apply its default model, currently `gpt-5.4`.

This behavior is documented in the README and validated by the test suite in `tests/commands.test.mjs`.

```bash
node scripts/codex-companion.mjs task "Generate unit tests for the existing module"

```

## Model Propagation to the Runtime

After resolution, the normalized model value is attached to the request object as `request.model`. This value is forwarded through the `runAppServerTurn` or `runAppServerReview` helpers and ultimately transmitted to the Codex runtime via the `model` field of the turn or review payload.

Programmatic usage allows direct specification:

```js
import { runAppServerTurn } from "./plugins/codex/scripts/lib/codex.mjs";

const result = await runAppServerTurn(cwd, {
  prompt: "Explain the Visitor pattern",
  model: "gpt-5.3-codex-spark",   // explicit model
  sandbox: "read-only",
});

```

## Validation and Testing

The model selection logic is validated in `tests/runtime.test.mjs` (lines 766-784). These tests verify that:
- The "spark" alias correctly resolves to `gpt-5.3-codex-spark`
- The model selection is correctly transmitted through the app-server turn
- Missing model flags result in the expected default behavior

## Summary

- The Codex plugin uses a **command-line flag** (`--model`) to accept user model preferences across all commands.
- **Alias normalization** in `codex-companion.mjs` converts shorthand names like "spark" to canonical model identifiers (`gpt-5.3-codex-spark`).
- When no model is specified, the system defaults to **gpt-5.4** via the Codex service's internal selection.
- The **normalized model value** propagates through `request.model` to the runtime payload.
- All behavior is validated by the **test suite** in `tests/runtime.test.mjs`.

## Frequently Asked Questions

### What happens if I don't specify a model when running a Codex task?

If you omit the `--model` flag, the `normalizeRequestedModel` function returns `null`, and the `runAppServerTurn` helper in `plugins/codex/scripts/lib/codex.mjs` allows the Codex service to apply its default model, which is currently `gpt-5.4`.

### Can I use custom model names or only predefined aliases?

You can specify any valid model name supported by the Codex service. The alias system only provides shortcuts for convenience; if you provide a full model identifier that isn't in the `MODEL_ALIASES` map, it passes through unchanged to the runtime.

### How do I use the "spark" model alias in the Codex plugin?

Pass `--model spark` to any supported command. The `normalizeRequestedModel` function in `codex-companion.mjs` automatically expands this to `gpt-5.3-codex-spark` before sending the request to the underlying service.

### Where is the model selection logic tested?

The test suite in `tests/runtime.test.mjs` (lines 766-784) validates the entire model selection pipeline, ensuring aliases resolve correctly and that the model parameter reaches the app-server turn as expected.