Difference Between --model and --effort Parameters in the Codex Plugin

The --model flag selects which language model Codex uses (e.g., gpt-5.4-mini or spark), while --effort controls the reasoning depth (compute budget) for that model, ranging from none to xhigh.

The openai/codex-plugin-cc repository provides a command-line wrapper that forwards runtime options to the Codex app-server. Understanding the difference between --model and --effort parameters is essential for controlling both the intelligence backend and the computational resources allocated to your coding tasks.

What --model and --effort Control

Model Selection with --model

The --model parameter determines which specific language model processes your request. According to the source code in plugins/codex/scripts/codex-companion.mjs, valid inputs include specific model identifiers like gpt-5.4-mini or the alias spark, which expands to gpt-5.3-codex-spark. The normalizeRequestedModel function (lines 103–112) handles this normalization before adding the value to the request payload as the model field.

Reasoning Effort with --effort

The --effort parameter configures how much compute time and search depth the model should expend. Acceptable values are none, minimal, low, medium, high, and xhigh. In the same source file, the normalizeReasoningEffort function (lines 114–126) validates and normalizes this input, placing the result in the request payload as effort. Higher effort levels can yield more thorough analysis but at increased cost.

How the Codex Plugin Processes These Parameters

The parameter flow begins in codex-companion.mjs, where parseCommandInput calls parseArgs from lib/args.mjs to extract user inputs.

For model selection:

1. Raw --model value is captured by argument parsing
2. normalizeRequestedModel validates and normalizes the value
3. Result is added to JSON payload as model

For reasoning effort:

1. Raw --effort value is captured similarly
2. normalizeReasoningEffort maps the string to valid effort levels
3. Result is added to JSON payload as effort

As shown in tests/fake-codex-fixture.mjs (lines 451–452), the final payload sent to the Codex app-server contains both fields:

{
  "model": "gpt-5.4-mini",
  "effort": "medium"
}

Both parameters are optional. As documented in the README (lines 61–63) and verified in tests/commands.test.mjs (lines 107–115), omitting these flags allows Codex to select its own defaults based on user configuration.

Practical Usage Examples

Here are concrete examples demonstrating the difference between these parameters.

Use the default model and effort (omitting both flags):

codex:rescue "investigate why the flaky test fails"

Specify a model but use default effort:

codex:rescue --model spark "fix the flaky test quickly"

Use default model but increase reasoning depth:

codex:rescue --effort high "perform a deep analysis of the failing test"

Explicitly configure both model and effort level:

codex:rescue --model gpt-5.4-mini --effort medium "refactor the data layer"

Summary

• The --model parameter selects the backend language model (e.g., gpt-5.4-mini, spark → gpt-5.3-codex-spark), processed by normalizeRequestedModel in codex-companion.mjs.
• The --effort parameter controls computational depth across six levels (none to xhigh), processed by normalizeReasoningEffort.
• Both values are normalized and added to the JSON request payload sent to the Codex app-server.
• These flags are optional; when omitted, Codex applies default settings from user configuration.
• Together, they provide fine-grained control over the cost-quality trade-off without editing configuration files.

Frequently Asked Questions

What happens if I don't specify --model or --effort in the Codex plugin?

If you omit these parameters, the plugin does not set explicit values in the request payload. According to the README and test suite, Codex automatically selects its own defaults based on your user configuration, using the model and effort level defined in your Codex settings.

Can I use --effort with any model in the Codex plugin?

Yes. The --effort parameter operates independently of model selection. You can apply any effort level (none through xhigh) to any model specified via --model, allowing you to control reasoning depth regardless of whether you use gpt-5.4-mini, spark (which expands to gpt-5.3-codex-spark), or other supported models.

How does the spark alias work with the --model parameter?

The spark alias is a convenience shorthand defined in the Codex plugin source code. When you pass --model spark, the normalizeRequestedModel function maps this to gpt-5.3-codex-spark, a specialized model optimized for specific Codex workflows, before adding it to the request payload.

Where does the Codex plugin validate these parameters?

Validation occurs in plugins/codex/scripts/codex-companion.mjs. The normalizeRequestedModel function (lines 103–112) handles model validation, while normalizeReasoningEffort (lines 114–126) ensures effort values match the accepted enum of none, minimal, low, medium, high, or xhigh before constructing the final JSON request.

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