# How to Configure Custom Models and Reasoning Effort for Codex Tasks

> Learn to configure custom models and reasoning effort for Codex tasks. Use CLI flags or a config file for flexible control over your development workflow.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: how-to-guide
- Published: 2026-07-15

---

**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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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:

```toml
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:

```javascript
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:

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/.codex/config.toml) in your repository root to establish consistent defaults for all team members:

```bash
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:

```bash

# 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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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`](https://github.com/openai/codex-plugin-cc/blob/main/.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.