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

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.

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.

# 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 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 in your project root for repository-specific settings.

# .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.

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

# 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 at your repository root:

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:

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 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}