# Codex Reasoning Effort Levels and Model Aliases: Complete Reference for the OpenAI Plugin

> Discover Codex reasoning effort levels none minimal low medium high xhigh and the spark model alias for the OpenAI plugin. Get the complete reference for optimal performance.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-07-09

---

**The Codex plugin supports six reasoning effort levels (none, minimal, low, medium, high, xhigh) and one model alias (spark → gpt-5.3-codex-spark), validated against fixed Sets in the companion script.**

The openai/codex-plugin-cc repository provides the official command-line interface and programmatic API for controlling Codex execution. Understanding the supported reasoning effort levels and model aliases is essential for optimizing the trade-off between response quality and latency in your development workflow.

## Supported Reasoning Effort Levels

The plugin defines a strict validation set called **VALID_REASONING_EFFORTS** that constrains how much computational reasoning the model applies to a task.

### The Six Valid Reasoning Effort Values

In `plugins/codex/scripts/codex-companion.mjs`, the valid options are declared as:

```ts
const VALID_REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);

```

Each value controls the specific trade-off between response speed and thoroughness:

- **none**: No extra reasoning time; the model responds as quickly as possible
- **minimal**: Very little additional computation
- **low**: A modest amount of extra reasoning
- **medium**: The default amount used when no value is specified
- **high**: More thorough reasoning for complex prompts
- **xhigh**: The maximum level of reasoning effort available

Any value outside this set triggers an error when processed by `normalizeReasoningEffort`.

## Model Aliases in Codex

Rather than requiring full model identifiers, the plugin supports shorthand aliases through the **MODEL_ALIASES** Map.

### The Spark Alias

The current alias mapping is defined in `plugins/codex/scripts/codex-companion.mjs`:

```ts
const MODEL_ALIASES = new Map([["spark", "gpt-5.3-codex-spark"]]);

```

When you pass `--model spark` to the CLI or include `model: "spark"` in the programmatic API, the helper function `normalizeRequestedModel` expands this to the full identifier `gpt-5.3-codex-spark`. Any string not matching a known alias passes through unchanged to the underlying service.

## Normalization and Validation Logic

The plugin validates inputs through two key functions before constructing requests.

### Input Normalization Functions

- **normalizeRequestedModel**: Consults `MODEL_ALIASES` to expand shorthand names; returns unmodified strings for unrecognized values
- **normalizeReasoningEffort**: Checks against `VALID_REASONING_EFFORTS`; throws an error for unsupported values

These functions are called internally by `buildTaskRequest` in `plugins/codex/scripts/lib/codex.mjs`, ensuring all requests meet the schema requirements before reaching the app server.

## Practical Usage Examples

### CLI Usage with codex-companion.mjs

Execute tasks with specific reasoning levels and model aliases directly from the command line:

```bash
node scripts/codex-companion.mjs task \
  --model spark \
  --effort high \
  "Refactor this function to use async/await"

```

This command normalizes `spark` to `gpt-5.3-codex-spark` and sets the reasoning effort to `high` before sending the request to the app server.

### Programmatic API Integration

Import `buildTaskRequest` to construct valid requests within your own plugins:

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

const request = buildTaskRequest({
  cwd: process.cwd(),
  model: "spark",        // Expands to gpt-5.3-codex-spark
  effort: "low",         // Must be in VALID_REASONING_EFFORTS
  prompt: "Optimize database queries",
  write: false,
  resumeLast: false,
  jobId: undefined,
});

```

### Handling Invalid Reasoning Efforts

Attempting to use an unsupported effort level throws a descriptive error:

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

```

## Summary

- The **VALID_REASONING_EFFORTS** Set in `plugins/codex/scripts/codex-companion.mjs` restricts inputs to six specific values: none, minimal, low, medium, high, and xhigh
- The **MODEL_ALIASES** Map currently supports only one alias: `spark` → `gpt-5.3-codex-spark`
- Functions `normalizeRequestedModel` and `normalizeReasoningEffort` validate inputs before request construction via `buildTaskRequest`
- When omitted, Codex defaults to `gpt-5.4` with `medium` reasoning effort
- Invalid effort values throw explicit errors listing all supported options

## Frequently Asked Questions

### What happens if I don't specify a reasoning effort or model?

When you omit the `--effort` or `--model` flags, the plugin leaves both values unset. According to the implementation in `openai/codex-plugin-cc`, the underlying Codex service applies its own defaults: typically `gpt-5.4` for the model and `medium` for the reasoning effort level.

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

The **MODEL_ALIASES** Map is hardcoded in `plugins/codex/scripts/codex-companion.mjs` with only the `spark` entry. To add custom aliases, you would need to modify the source code and add entries to the Map initialization before the plugin loads.

### What is the difference between high and xhigh reasoning effort?

Both values increase processing time beyond the default, but **xhigh** represents the maximum reasoning budget available in the Codex plugin, while **high** provides substantial analysis without reaching the upper limit. Use **xhigh** for complex architectural decisions and **high** for detailed code reviews.

### How do I validate reasoning effort before sending a request?

You can import and call `normalizeReasoningEffort` from the companion script utilities to pre-validate values. This function checks against `VALID_REASONING_EFFORTS` and throws an error with the complete list of valid options if the input is invalid.