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

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:

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.

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:

# 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 (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	Lists the alias in skill definitions (lines 23-29)
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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}