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

> Understand the difference between --model and --effort in the Codex plugin. Learn how to select a language model and control its reasoning depth for optimal results.

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

---

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

```json
{
  "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):

```bash
codex:rescue "investigate why the flaky test fails"

```

Specify a model but use default effort:

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

```

Use default model but increase reasoning depth:

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

```

Explicitly configure both model and effort level:

```bash
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.