# How to Configure Reasoning Effort for the Codex Plugin: CLI and Config Options

> Learn how to configure reasoning effort for the Codex plugin using CLI flags or config options. Explore all six supported effort levels for optimized performance.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-12

---

**The Codex plugin supports six reasoning effort levels—`none`, `minimal`, `low`, `medium`, `high`, and `xhigh`—configurable via the `--effort` CLI flag or the `model_reasoning_effort` key in [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml).**

The openai/codex-plugin-cc repository provides granular control over model reasoning depth through explicit configuration options. Understanding how to set reasoning effort ensures you balance computational cost against output quality for your specific use case.

## Supported Reasoning Effort Values

The plugin recognizes exactly six distinct effort levels defined in the `VALID_REASONING_EFFORTS` Set within `plugins/codex/scripts/codex-companion.mjs`:

- `none` – No additional reasoning
- `minimal` – Minimal computational effort
- `low` – Reduced reasoning depth
- `medium` – Balanced approach
- `high` – Extended analysis
- `xhigh` – Maximum reasoning depth

These values are case-insensitive and normalized to lowercase before validation occurs.

## Configuration Methods

You can configure reasoning effort through two primary mechanisms, with CLI flags taking precedence over config file settings.

### Using the `--effort` CLI Flag

Pass the `--effort` flag followed by your desired level when running commands like `task`, `rescue`, or `review`. This overrides any default settings for that specific invocation.

```bash

# Run with low reasoning effort

node scripts/codex-companion.mjs task --effort low "Explain this code"

# Rescue with maximum effort

node scripts/codex-companion.mjs rescue --effort xhigh 12345

```

### Using the [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) File

Set a persistent default by adding `model_reasoning_effort` to your configuration file. Place this at `~/.codex/config.toml` for user-level defaults or [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in your project root for repository-specific settings.

```toml

# .codex/config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

```

## Validation and Error Handling

The plugin validates inputs through the `normalizeReasoningEffort` function in `plugins/codex/scripts/codex-companion.mjs`. This helper converts inputs to lowercase, checks membership against `VALID_REASONING_EFFORTS`, and throws descriptive errors for invalid values.

```js
// plugins/codex/scripts/codex-companion.mjs
function normalizeReasoningEffort(effort) {
  if (effort == null) return null;
  const normalized = String(effort).trim().toLowerCase();
  if (!VALID_REASONING_EFFORTS.has(normalized)) {
    throw new Error(
      `Unsupported reasoning effort "${effort}". Use one of: none, minimal, low, medium, high, xhigh.`
    );
  }
  return normalized;
}

```

Attempting to use an unsupported value results in immediate termination with a clear error message listing all valid options.

## Practical Code Examples

### Override Config Defaults via CLI

When you need temporary deviation from your configured default:

```bash

# Config sets medium, but this task needs minimal effort

node scripts/codex-companion.mjs review --effort minimal src/utils.js

```

### Project-Level Configuration

Create [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) at your repository root:

```toml
model = "gpt-5.4-mini"
model_reasoning_effort = "high"

```

Now all team members using this repository automatically use high reasoning effort unless they explicitly override with `--effort`.

### Error Handling Demonstration

Invalid inputs trigger immediate validation errors:

```bash
node scripts/codex-companion.mjs task --effort super "Do something"

# Error: Unsupported reasoning effort "super". Use one of: none, minimal, low, medium, high, xhigh.

```

## Summary

- The **Codex plugin** supports six reasoning effort levels: `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
- Configure via the **`--effort` CLI flag** for per-command overrides or **`model_reasoning_effort`** in [`config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/config.toml) for persistent defaults.
- Validation occurs in **`normalizeReasoningEffort`** within `plugins/codex/scripts/codex-companion.mjs`, which enforces the whitelist and provides clear error messages.
- CLI flags always take precedence over configuration file settings.
- Config files can reside at `~/.codex/config.toml` (user-level) or [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) (project-level).

## Frequently Asked Questions

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

When no value is provided, the `normalizeReasoningEffort` function returns `null`, allowing the underlying model to use its default behavior. This typically equates to `medium` effort, though the exact behavior depends on the specific model implementation.

### Can I use different reasoning efforts for different commands in the same project?

Yes. Set a baseline in [`.codex/config.toml`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) using `model_reasoning_effort`, then override specific commands with the `--effort` flag. For example, use `high` for complex `rescue` operations while keeping `low` for routine `task` invocations.

### Does the reasoning effort affect token usage and latency?

Higher effort levels like `high` and `xhigh` generally consume more tokens and increase response time as the model performs deeper analysis. Conversely, `none` and `minimal` reduce computational overhead and cost but may sacrifice accuracy on complex reasoning tasks.

### Where is the validation logic located in the source code?

The validation logic resides in `plugins/codex/scripts/codex-companion.mjs`, specifically within the `normalizeReasoningEffort` function and the `VALID_REASONING_EFFORTS` Set constant. These enforce the six valid values and handle input normalization.