How to Configure Model Reasoning Effort (low/medium/high) in `.codex/config.toml`

Add model_reasoning_effort = "high" (or "low", "medium", etc.) to your .codex/config.toml file to set the default reasoning effort for all Codex model requests.

The OpenAI Codex plugin supports persistent configuration of reasoning effort through a TOML configuration file. This setting controls how much computational depth the model applies to each turn, with valid options ranging from none to xhigh. The configuration is read at startup and validated before every model call.

Where to Place the Configuration File

The plugin searches for .codex/config.toml in two locations:

• Project-level: At the root of the directory where you started the Codex session
• User-level: In your home directory (~/.codex/config.toml)

Project-level settings override user-level settings when both exist.

Valid Values for model_reasoning_effort

The codex-companion.mjs script enforces a strict set of allowed values. According to the source at plugins/codex/scripts/codex-companion.mjs (line 124), the valid options are:

Value	Description
none	No additional reasoning
minimal	Minimal reasoning overhead
low	Reduced reasoning for faster responses
medium	Balanced reasoning (default when omitted)
high	Deeper reasoning for complex tasks
xhigh	Maximum reasoning depth

An invalid value triggers this error:

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

Configuration Examples

Basic High-Effort Setup

Create .codex/config.toml at your project root:

# .codex/config.toml

model_reasoning_effort = "high"

Combining with Model Selection

Specify both the model and reasoning effort:

# .codex/config.toml

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

With this configuration, every turn uses gpt-5.4-mini with high reasoning effort unless explicitly overridden.

Command-Line Override

Use the --effort flag to temporarily bypass the config file:

codex review --effort low

This single invocation uses low effort regardless of the .codex/config.toml setting.

How the Configuration Flow Works

The architectural implementation in openai/codex-plugin-cc follows this sequence:

1. Load .codex/config.toml via the Codex core configuration loader
2. Extract model_reasoning_effort if the key exists
3. Pass the value to the turn-initialization logic in codex-companion.mjs
4. Validate against the allowed enum (none, minimal, low, medium, high, xhigh)
5. Apply the validated effort to all subsequent model calls

The plugins/codex/scripts/lib/codex.mjs module manages turn state, including the reasoning-effort metadata that flows into each request. If model_reasoning_effort is absent from config, the plugin falls back to "medium" as the built-in default.

Key Source Files

Understanding these files helps with debugging configuration issues:

• plugins/codex/scripts/codex-companion.mjs — Validates and applies model_reasoning_effort; contains the error message for invalid values
• plugins/codex/scripts/lib/codex.mjs — Handles turn state and reasoning-effort metadata propagation
• README.md (lines 273-277) — Documents the user-level configuration format with examples
• plugins/codex/commands/*.md — CLI documentation showing optional --effort flag usage

Summary

• Set model_reasoning_effort in .codex/config.toml for persistent default behavior
• Choose from six validated levels: none, minimal, low, medium, high, xhigh
• Override per-command with --effort flag
• Locate config at project root (./.codex/config.toml) or user home (~/.codex/config.toml)
• Expect "medium" fallback when the key is omitted

Frequently Asked Questions

What happens if I specify an invalid reasoning effort value?

The codex-companion.mjs validator throws an error immediately on startup or turn initialization, listing all six supported values. The session will not proceed until you correct the configuration file.

Can I set different reasoning efforts for different models?

Not directly in the config file. The model_reasoning_effort key applies globally to all model calls. To vary effort by model, use command-line --effort flags or script multiple Codex sessions with separate config directories.

Does the command-line --effort flag always override the config file?

Yes. According to the CLI implementation documented in plugins/codex/commands/*.md, explicit --effort values take precedence over .codex/config.toml settings for that single invocation only.

Where does the plugin look for config.toml first—project or user level?

The plugin checks the project-level .codex/config.toml first (relative to the working directory where Codex was started), then falls back to ~/.codex/config.toml if not found. Project settings override user settings when both exist.

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