# How the Codex Plugin Handles Reasoning Effort Settings: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`

> Discover how the Codex plugin manages reasoning effort settings like none, minimal, low, medium, high, and xhigh. Learn how it validates and forwards these settings to the Codex API.

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

---

**The Codex plugin validates `--effort` flag values against a whitelist of six identifiers, normalizes the input, and forwards it to the Codex API without modification.**

The `openai/codex-plugin-cc` repository provides a command-line interface for running Codex tasks. A critical configuration option is the **reasoning effort** setting, which controls how much internal "thinking" the model applies to a task. This article examines how the plugin parses, validates, and propagates the `--effort` flag through its architecture.

## Supported Reasoning Effort Values

The plugin accepts exactly six string identifiers for the `--effort` flag:

- `none`
- `minimal`
- `low`
- `medium`
- `high`
- `xhigh`

Any other value triggers a validation error. This whitelist is defined in `plugins/codex/scripts/codex-companion.mjs` at lines 71-72:

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

```

## Normalization and Validation with `normalizeReasoningEffort`

When the CLI parses arguments, it delegates effort handling to the `normalizeReasoningEffort` function. This function performs three operations:

1. Returns `null` if the flag is omitted
2. Trims and lower-cases the input string
3. Validates against `SUPPORTED_EFFORTS` or throws an error

The implementation appears in `plugins/codex/scripts/codex-companion.mjs` at lines 14-27:

```javascript
function normalizeReasoningEffort(value) {
  if (value === undefined || value === null) {
    return null;  // Let Codex use its default
  }
  const normalized = value.toString().trim().toLowerCase();
  if (!SUPPORTED_EFFORTS.has(normalized)) {
    throw new Error(
      `Unsupported reasoning effort "${value}". ` +
      `Use one of: ${[...SUPPORTED_EFFORTS].join(", ")}.`
    );
  }
  return normalized;
}

```

This strict validation ensures the API receives only recognized values.

## Propagation to the Task Request

After normalization, the validated effort value flows into the task request payload. Inside the `buildTaskRequest` function at line 490 of `codex-companion.mjs`, the `effort` field is conditionally added:

```javascript
const request = {
  model,
  prompt,
  // ... other fields
};
if (effort !== null) {
  request.effort = effort;  // Only include when explicitly set
}

```

The request object then passes to `plugins/codex/scripts/lib/codex.mjs`, which serializes it for the Codex service API. The library forwards the `effort` field unchanged.

## Runtime Behavior and Defaults

The Codex backend interprets the `effort` value to adjust internal reasoning characteristics—such as the number of thinking passes or depth of analysis. The concrete mapping from effort levels to computational behavior resides in the closed-source Codex service, not the plugin.

When `--effort` is omitted, the plugin deliberately excludes the field from the request. According to the test suite in `tests/commands.test.mjs` (lines 107-158), this allows Codex to apply its own default, currently `medium`. The documentation recommends: *"Leave `--effort` unset unless the user explicitly asks for a specific reasoning effort."*

## Usage Examples

### Running a Task with Low Reasoning Effort

```bash
node scripts/codex-companion.mjs task --model spark --effort low "Diagnose the failing test"

```

The normalized value `"low"` reaches the Codex API, triggering a lightweight analysis strategy.

### Using Default Reasoning Effort

```bash
node scripts/codex-companion.mjs task "Explain the plugin architecture"

```

No `effort` field is transmitted. Codex applies its internal default.

### Invalid Values Produce Clear Errors

```bash
node scripts/codex-companion.mjs task --effort turbo "Run quick analysis"

```

Output:

```

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

```

## Key Source Files

| File | Responsibility |
|------|--------------|
| `plugins/codex/scripts/codex-companion.mjs` | CLI entry point; parses, normalizes, and validates `--effort`; builds request payload |
| `plugins/codex/scripts/lib/codex.mjs` | Client library; forwards `effort` field to Codex API |
| `tests/commands.test.mjs` | Documents accepted values and default behavior expectations |
| `tests/runtime.test.mjs` | Verifies effort flag propagation to app-server turn start |

## Summary

- The plugin accepts **six specific effort values**: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`
- `normalizeReasoningEffort` in `codex-companion.mjs` handles **validation and normalization** with strict error handling
- Valid values propagate to the **task request payload** at line 490 of `codex-companion.mjs`
- The plugin **omits the field entirely** when `--effort` is not specified, deferring to Codex defaults
- The Codex service performs the actual **reasoning effort adjustment**; the plugin only validates and forwards

## Frequently Asked Questions

### What happens if I omit the `--effort` flag?

The plugin does not include an `effort` field in the API request. According to `tests/commands.test.mjs`, this lets Codex apply its own default—currently `medium`—as defined by the backend service.

### Can I use custom effort values like `turbo` or `maximum`?

No. The plugin rejects any value outside the six supported identifiers. The `normalizeReasoningEffort` function throws an error listing the allowed options: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`.

### Is effort case-sensitive?

No. The normalization step converts input to lowercase, so `--effort HIGH`, `--effort high`, and `--effort High` all resolve to `"high"`.

### Where does the actual reasoning effort adjustment happen?

In the Codex backend service. The plugin's responsibility ends at validation and forwarding. The closed-source service maps the `effort` string to internal computational parameters like thinking passes or search depth.