How to Configure the Codex Model and Reasoning Effort for the openai/codex-plugin-cc Plugin

You can configure the Codex model and reasoning effort via a .codex/config.toml file for project-level defaults or override them per-command using --model and --effort flags.

The openai/codex-plugin-cc repository provides flexible configuration options that let you control which AI model processes your tasks and how much computational effort it applies. You can set these parameters globally for your entire project or adjust them dynamically for individual commands. This guide covers the specific file locations, validation logic, and API propagation paths defined in the source code.

Project-Level Configuration with .codex/config.toml

Create a .codex/config.toml file at the root of your repository to establish default settings for all plugin commands.

model = "gpt-5.4-mini"          # Default model for all plugin commands

model_reasoning_effort = "high" # Default reasoning effort level

The plugin recognizes six valid values for model_reasoning_effort: none, minimal, low, medium, high, and xhigh.

Configuration Precedence and Trust Levels

The plugin loads configuration files in the following order:

1. User-level config at ~/.codex/config.toml
2. Project-level config at .codex/config.toml (loaded only when the project is trusted)

If you omit command-line flags, the plugin falls back to these configuration values before allowing Codex to use its internal defaults.

Command-Line Runtime Overrides

All task-type commands—including /codex:review, /codex:rescue, and /codex:task—accept two runtime-selection flags that override configuration file settings:

• --model <model|spark> – Selects a specific model. The special value spark maps internally to gpt-5.3-codex-spark.
• --effort <level> – Sets reasoning effort to none, minimal, low, medium, high, or xhigh.

When you invoke a command, the plugin validates the --effort flag in codex-companion.mjs through the normalizeReasoningEffort function, which ensures only the six allowed values are accepted.

How Settings Propagate to the Codex Server

After validation, the plugin forwards your selections to the Codex app-server via the turn/start API call. The implementation in plugins/codex/scripts/lib/codex.mjs handles this propagation:

• Model handling – Line 66 passes the value: model: options.model ?? null
• Reasoning effort handling – Line 1140 passes the value: effort: options.effort ?? null

If you do not provide --model or --effort flags, these fields remain null and the Codex server applies its own defaults.

Practical Usage Examples

Use the project defaults with /codex:review:

/codex:review --background

Override the model for a single invocation using the spark shorthand:

/codex:review --model spark --background

Adjust only the reasoning effort to reduce processing time:

/codex:review --effort low --background

Specify both model and effort explicitly for complex rescue operations:

/codex:rescue --model gpt-5.4-mini --effort high

As documented in plugins/codex/commands/rescue.md (line 45), these flags apply consistently across all task commands.

Summary

• Configure defaults in .codex/config.toml using model and model_reasoning_effort keys.
• Trust requirement – Project-level configs load only for trusted repositories.
• Override per-command with --model and --effort flags available on /codex:review, /codex:rescue, and /codex:task.
• Validation occurs in codex-companion.mjs via normalizeReasoningEffort.
• Propagation happens through plugins/codex/scripts/lib/codex.mjs (lines 66 and 1140) to the turn/start API endpoint.

Frequently Asked Questions

What are the valid values for the reasoning effort setting?

The model_reasoning_effort configuration key and --effort flag accept six values: none, minimal, low, medium, high, and xhigh. These are validated in the normalizeReasoningEffort function within codex-companion.mjs before being sent to the Codex server.

Can I use different models for different commands in the same project?

Yes. While the .codex/config.toml file sets project-wide defaults, you can override the model for any single command using the --model flag. For example, use --model spark (which maps to gpt-5.3-codex-spark) for quick tasks and --model gpt-5.4-mini for comprehensive reviews.

Why is my project-level configuration not loading?

The plugin only loads .codex/config.toml when the project is marked as trusted. If your configuration values are not applying, verify that the repository has been trusted in your development environment. User-level settings at ~/.codex/config.toml load regardless of trust status.

What happens if I do not specify a model or effort?

If you omit both configuration file entries and command-line flags, the plugin sends null values for these fields to the Codex server via the turn/start API call. The Codex backend then applies its own internal defaults, as documented in the repository README.

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