# Model Aliases and Reasoning Effort Options in the OpenAI Codex Plugin

> Explore model aliases and reasoning effort options in the OpenAI Codex plugin. Learn how to control code generation with effort levels from none to xhigh and use the spark alias.

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

---

**The OpenAI Codex plugin supports six reasoning effort levels (`none` to `xhigh`) and one model alias (`spark` → `gpt-5.3-codex-spark`), validated via `VALID_REASONING_EFFORTS` and `MODEL_ALIASES` in `codex-companion.mjs`.**

The `openai/codex-plugin-cc` repository provides the reference implementation for integrating Codex into development environments. Understanding the available **model aliases and reasoning effort options** helps you control response latency and quality when invoking the Codex CLI or programmatic API. These configurations are validated against strict Sets and Maps defined in the companion script.

## Supported Reasoning Effort Levels

The plugin defines acceptable reasoning values in a `Set` named `VALID_REASONING_EFFORTS` located in `plugins/codex/scripts/codex-companion.mjs`. This validation ensures only six specific string values reach the underlying Codex API.

The supported effort levels are:

- **`none`** – No additional reasoning; optimizes for response speed
- **`minimal`** – Negligible computational overhead
- **`low`** – Modest reasoning suitable for straightforward tasks
- **`medium`** – Default effort applied when the user omits the flag
- **`high`** – Extensive reasoning for complex logic requirements
- **`xhigh`** – Maximum reasoning depth for challenging prompts

When you omit the effort parameter, Codex defaults to `medium` reasoning with the standard `gpt-5.4` model configuration.

## Model Alias Mapping

Instead of entering full model identifiers, you can use shorthand aliases maintained in the `MODEL_ALIASES` Map. Currently, the plugin supports a single alias:

- **`spark`** → expands to **`gpt-5.3-codex-spark`**

The helper function `normalizeRequestedModel` consults this Map in `plugins/codex/scripts/codex-companion.mjs`. If your input matches a defined alias, the function returns the full model string; otherwise, it passes your input through unchanged to the API.

## Configuration Examples

### Command Line Interface

Pass `--model` and `--effort` flags to the companion script:

```bash
node scripts/codex-companion.mjs task \
  --model spark \
  --effort low \
  "Explain optimistic concurrency control"

```

This expands `spark` to `gpt-5.3-codex-spark` and sets the reasoning effort to `low`.

### Programmatic API

When building requests via `buildTaskRequest` in `plugins/codex/scripts/lib/codex.mjs`:

```typescript
import { buildTaskRequest } from "./plugins/codex/scripts/lib/codex.mjs";

const request = buildTaskRequest({
  cwd: process.cwd(),
  model: "spark",               // Normalized to gpt-5.3-codex-spark
  effort: "high",               // Must be in VALID_REASONING_EFFORTS
  prompt: "Refactor authentication logic",
  write: false,
  resumeLast: false,
  jobId: undefined,
});

```

### Error Handling

Invalid effort values trigger errors via `normalizeReasoningEffort`:

```typescript
try {
  const effort = normalizeReasoningEffort("ultra");
} catch (e) {
  console.error(e.message);
  // → "Unsupported reasoning effort \"ultra\". Use one of: none, minimal, low, medium, high, xhigh."
}

```

## Implementation Details

The validation and normalization logic resides in these key files:

- `plugins/codex/scripts/codex-companion.mjs` – Defines `VALID_REASONING_EFFORTS` and `MODEL_ALIASES`; exports `normalizeRequestedModel` and `normalizeReasoningEffort`
- `plugins/codex/scripts/lib/codex.mjs` – Implements `buildTaskRequest` which consumes normalized values
- `plugins/codex/scripts/lib/args.mjs` – Parses `--model` and `--effort` CLI arguments

## Summary

- The Codex plugin recognizes six discrete reasoning efforts: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`
- A single model alias maps `spark` to `gpt-5.3-codex-spark` via the `MODEL_ALIASES` Map
- Both CLI and programmatic interfaces validate inputs through `normalizeReasoningEffort` and `normalizeRequestedModel`
- Omitting these options triggers defaults: typically `gpt-5.4` with `medium` reasoning effort

## Frequently Asked Questions

### What happens if I specify an invalid reasoning effort?

The `normalizeReasoningEffort` function throws a descriptive error enumerating all valid options from `VALID_REASONING_EFFORTS`. The message explicitly lists: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.

### Can I add custom model aliases to the Codex plugin?

The `MODEL_ALIASES` Map in `codex-companion.mjs` currently hardcodes only the `spark` entry. To support additional aliases, you must modify the source Map directly; otherwise, unknown strings pass through unchanged to the underlying model API.

### Does the reasoning effort affect token usage or billing?

Higher effort levels like `high` and `xhigh` typically increase processing time and may consume additional tokens during internal reasoning steps. The plugin documentation recommends leaving both flags unset unless you explicitly require control over these parameters.

### Which model and effort level runs by default?

When you omit both the `--model` and `--effort` flags, Codex selects its own defaults—typically `gpt-5.4` with `medium` reasoning effort—unless overridden by server-side configuration.