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

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:

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.

// 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:

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

3. Alias Lookup

The normalized string is checked against MODEL_ALIASES:

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:

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:

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:

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.

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