How to Specify and Use Different Codex Models (e.g., gpt-5.4-mini, spark) with the Plugin

The openai/codex-plugin-cc repository supports model selection via the --model CLI flag or model option in code, with automatic alias resolution for shortcuts like spark.

The openai/codex-plugin-cc plugin provides flexible model selection, allowing you to specify any Codex model identifier or use convenient aliases when running tasks. Whether you need the lightweight gpt-5.4-mini for quick iterations or want to leverage the spark variant for specialized workloads, the plugin handles model normalization and propagation automatically.

How Model Selection Works in the Codex Plugin

The plugin implements a three-stage pipeline for model specification that ensures your requested model reaches the Codex service correctly.

CLI Argument Parsing in codex-companion.mjs

The entry point plugins/codex/scripts/codex-companion.mjs captures the --model argument through parseCommandInput. This raw value undergoes normalization before being passed to the execution layer.

Model Name Normalization

The normalizeRequestedModel function handles all model string processing. Located in codex-companion.mjs, this function:

• Trims whitespace from the input
• Checks against the MODEL_ALIASES map for shorthand expansions
• Returns unmapped strings unchanged for direct model identifiers

function normalizeRequestedModel(model) {
  if (model == null) return null;
  const normalized = String(model).trim();
  if (!normalized) return null;
  return MODEL_ALIASES.get(normalized.toLowerCase()) ?? normalized;
}

The alias map includes "spark" → "gpt-5.3-codex-spark", enabling you to use the shorter form in commands.

Request Propagation to Codex Service

After normalization, the model string attaches to options.model and forwards through plugins/codex/scripts/lib/codex.mjs to the underlying Codex client. This ensures the specified model parameter reaches the service API without modification.

Supported Model Specification Methods

You can specify models in three ways when using the Codex plugin:

• Direct model identifier — Pass full names like gpt-5.4-mini or gpt-5.4-large for explicit control
• Alias shorthand — Use spark to automatically expand to gpt-5.3-codex-spark
• Default behavior — Omit --model entirely to let Codex apply its internal heuristics

CLI Examples for Model Selection

Use the --model flag with the task command to select your preferred Codex model:

# Specify the full model name directly

node plugins/codex/scripts/codex-companion.mjs task \
     --model gpt-5.4-mini --effort medium "Refactor the login flow"

# Use the spark alias for the gpt-5.3-codex-spark variant

node plugins/codex/scripts/codex-companion.mjs task \
     --model spark --effort low "Diagnose the failing test"

Programmatic Model Configuration

When importing the library directly, pass the model option to runTask:

import { runTask } from "./plugins/codex/scripts/lib/codex.mjs";

// Explicit full model name
await runTask({
  cwd: process.cwd(),
  model: "gpt-5.4-mini",
  effort: "medium",
  prompt: "Generate a summary of the changelog."
});

// Alias resolution happens automatically
await runTask({
  cwd: process.cwd(),
  model: "spark",
  effort: "low",
  prompt: "Diagnose the failing test."
});

The library handles alias expansion internally, so both approaches produce identical behavior to the CLI.

Test Verification of Alias Resolution

The mapping functionality is verified in tests/runtime.test.mjs. The test suite invokes the CLI with --model spark and asserts that the internal state records the expanded identifier:

// Test invocation from runtime.test.mjs line 776
run("node", [SCRIPT, "task", "--model", "spark", /* ... */])

// Assertion from runtime.test.mjs line 783
assert.equal(fakeState.lastTurnStart.model, "gpt-5.3-codex-spark")

This confirms that alias resolution occurs before model values reach the Codex service.

Key Source Files

File	Purpose
plugins/codex/scripts/codex-companion.mjs	Contains normalizeRequestedModel and CLI parsing logic
plugins/codex/scripts/lib/codex.mjs	Forwards normalized model option to Codex service
tests/runtime.test.mjs	Validates spark alias expansion to gpt-5.3-codex-spark

Summary

• The --model CLI flag and model option enable runtime model selection in openai/codex-plugin-cc
• Direct identifiers like gpt-5.4-mini pass through unchanged
• Alias spark automatically expands to gpt-5.3-codex-spark via MODEL_ALIASES
• The normalizeRequestedModel function in codex-companion.mjs handles all string processing
• Omitting --model delegates selection to Codex default heuristics

Frequently Asked Questions

What happens if I specify an invalid model name?

The plugin passes unmapped strings directly to the Codex service without validation. The service returns an error if the identifier is unrecognized. Always verify model availability against current Codex documentation.

Can I add custom model aliases?

The MODEL_ALIASES map is defined internally in codex-companion.mjs. To add custom aliases, you would need to modify the source code and rebuild the plugin. There is no runtime configuration for alias extensions.

Does model selection affect pricing or token limits?

Different Codex models have varying capabilities, context windows, and pricing structures. The plugin itself does not enforce limits—it merely forwards your selection. Consult OpenAI's Codex documentation for model-specific constraints and costs.

Is gpt-5.4-mini the same as the spark model?

No. gpt-5.4-mini is a distinct model identifier passed directly, while spark is an alias that resolves to gpt-5.3-codex-spark. These represent different model variants with separate characteristics.

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