How to Configure Custom Models and Reasoning Effort for Codex Tasks

You can configure custom models and reasoning effort for Codex tasks using the --model and --effort CLI flags for per-run overrides, or set persistent defaults in a .codex/config.toml configuration file that the plugin reads via the state.mjs module.

The openai/codex-plugin-cc repository provides a flexible configuration system that lets you control which AI model executes your tasks and how much computational reasoning to allocate. Whether you need a quick pass with minimal effort or deep analysis with extended reasoning, you can configure custom models and reasoning effort for Codex tasks through both command-line arguments and project-level configuration files.

CLI Argument Parsing and Normalization

The companion script at plugins/codex/scripts/codex-companion.mjs serves as the entry point for processing model and effort specifications. It extracts values from the --model (or -m) and --effort flags and validates them before constructing the task request.

Normalizing Model Names

The normalizeRequestedModel function (lines 3-12 in codex-companion.mjs) translates user-friendly aliases into concrete model identifiers. The alias spark automatically maps to gpt-5.3-codex-spark, while any other model name passes through unchanged to the backend.

Validating Reasoning Effort Levels

The normalizeReasoningEffort function (lines 14-27 in the same file) enforces strict validation on the effort parameter. It accepts only the following values: none, minimal, low, medium, high, or xhigh. This ensures that only supported reasoning configurations reach the Codex app-server.

Project-Level Configuration Defaults

The .codex/config.toml File

When you omit the CLI flags, the plugin falls back to configuration values stored in .codex/config.toml. The state.mjs module implements getConfig to read this file, checking first for project-level configurations before falling back to user-level settings according to the standard Codex configuration hierarchy.

Configuration Syntax

In plugins/codex/scripts/lib/state.mjs, the configuration loader expects TOML format with specific keys for model selection and reasoning intensity:

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

Task Request Construction

After normalization, the buildTaskRequest function (around lines 104-113 in codex-companion.mjs) assembles the final request object. This function merges the normalized model and effort values with the task prompt, working directory, and job metadata:

const model = normalizeRequestedModel(options.model);
const effort = normalizeReasoningEffort(options.effort);
const request = buildTaskRequest({
  cwd,
  model,
  effort,
  prompt,
  write,
  resumeLast,
  jobId: job.id
});

The resulting request object is then passed to runAppServerTurn to execute the task with your specified parameters.

Practical Configuration Examples

One-Off CLI Overrides

For ad-hoc tasks requiring different parameters than your defaults, use the --model and --effort flags directly:

# Use the spark alias with medium reasoning effort

/codex:task --model spark --effort medium "Refactor the authentication module"

Setting Project Defaults

Create a .codex/config.toml in your repository root to establish consistent defaults for all team members:

mkdir -p .codex
cat > .codex/config.toml <<'EOF'
model = "gpt-5.4-mini"
model_reasoning_effort = "high"
EOF

Combining Defaults with Temporary Overrides

You can override specific values on a per-run basis while keeping other defaults from the config file:

# Override only the reasoning effort for this specific task

/codex:task --effort low "Update the CI pipeline"

Summary

• The codex-companion.mjs script parses --model and --effort flags via the argument parsing utilities in plugins/codex/scripts/lib/args.mjs.
• The normalizeRequestedModel function maps the alias spark to gpt-5.3-codex-spark and passes other model names through unchanged.
• The normalizeReasoningEffort function validates effort levels against the accepted enum: none, minimal, low, medium, high, or xhigh.
• Project-level defaults reside in .codex/config.toml, read by the getConfig function in plugins/codex/scripts/lib/state.mjs.
• The buildTaskRequest function constructs the final payload by merging CLI overrides with configuration file defaults before sending to the app-server.

Frequently Asked Questions

What model names can I use with the --model flag?

The normalizeRequestedModel function in plugins/codex/scripts/codex-companion.mjs accepts any valid model identifier string. Additionally, it provides a convenience alias spark that maps to gpt-5.3-codex-spark. You can specify full model names like gpt-5.4-mini directly, and they pass through unchanged to the task request builder.

What happens if I don't specify --effort on the command line?

If you omit the --effort flag, the plugin calls getConfig from plugins/codex/scripts/lib/state.mjs to read your .codex/config.toml file. It uses the value assigned to model_reasoning_effort from that configuration, checking first for a project-level config in the current working directory, then falling back to user-level settings in your home directory.

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

Yes. While you can set a default model_reasoning_effort in .codex/config.toml, the --effort CLI flag always takes precedence for individual tasks. This layering allows you to use high for complex refactoring tasks but drop to low or minimal for simple documentation updates without modifying your project configuration file.

Where does the argument parsing happen before normalization?

The parseArgs function in plugins/codex/scripts/lib/args.mjs handles the initial CLI parsing, including the splitRawArgumentString utility. This occurs before the normalization functions process the values in codex-companion.mjs, ensuring that flags like -m and --model are correctly extracted into the options object passed to the normalization layer.

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