How the Codex Plugin Handles Reasoning Effort Settings: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`

The Codex plugin validates --effort flag values against a whitelist of six identifiers, normalizes the input, and forwards it to the Codex API without modification.

The openai/codex-plugin-cc repository provides a command-line interface for running Codex tasks. A critical configuration option is the reasoning effort setting, which controls how much internal "thinking" the model applies to a task. This article examines how the plugin parses, validates, and propagates the --effort flag through its architecture.

Supported Reasoning Effort Values

The plugin accepts exactly six string identifiers for the --effort flag:

• none
• minimal
• low
• medium
• high
• xhigh

Any other value triggers a validation error. This whitelist is defined in plugins/codex/scripts/codex-companion.mjs at lines 71-72:

const SUPPORTED_EFFORTS = new Set([
  "none", "minimal", "low", "medium", "high", "xhigh"
]);

Normalization and Validation with normalizeReasoningEffort

When the CLI parses arguments, it delegates effort handling to the normalizeReasoningEffort function. This function performs three operations:

1. Returns null if the flag is omitted
2. Trims and lower-cases the input string
3. Validates against SUPPORTED_EFFORTS or throws an error

The implementation appears in plugins/codex/scripts/codex-companion.mjs at lines 14-27:

function normalizeReasoningEffort(value) {
  if (value === undefined || value === null) {
    return null;  // Let Codex use its default
  }
  const normalized = value.toString().trim().toLowerCase();
  if (!SUPPORTED_EFFORTS.has(normalized)) {
    throw new Error(
      `Unsupported reasoning effort "${value}". ` +
      `Use one of: ${[...SUPPORTED_EFFORTS].join(", ")}.`
    );
  }
  return normalized;
}

This strict validation ensures the API receives only recognized values.

Propagation to the Task Request

After normalization, the validated effort value flows into the task request payload. Inside the buildTaskRequest function at line 490 of codex-companion.mjs, the effort field is conditionally added:

const request = {
  model,
  prompt,
  // ... other fields
};
if (effort !== null) {
  request.effort = effort;  // Only include when explicitly set
}

The request object then passes to plugins/codex/scripts/lib/codex.mjs, which serializes it for the Codex service API. The library forwards the effort field unchanged.

Runtime Behavior and Defaults

The Codex backend interprets the effort value to adjust internal reasoning characteristics—such as the number of thinking passes or depth of analysis. The concrete mapping from effort levels to computational behavior resides in the closed-source Codex service, not the plugin.

When --effort is omitted, the plugin deliberately excludes the field from the request. According to the test suite in tests/commands.test.mjs (lines 107-158), this allows Codex to apply its own default, currently medium. The documentation recommends: "Leave --effort unset unless the user explicitly asks for a specific reasoning effort."

Usage Examples

Running a Task with Low Reasoning Effort

node scripts/codex-companion.mjs task --model spark --effort low "Diagnose the failing test"

The normalized value "low" reaches the Codex API, triggering a lightweight analysis strategy.

Using Default Reasoning Effort

node scripts/codex-companion.mjs task "Explain the plugin architecture"

No effort field is transmitted. Codex applies its internal default.

Invalid Values Produce Clear Errors

node scripts/codex-companion.mjs task --effort turbo "Run quick analysis"

Output:

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

Key Source Files

File	Responsibility
plugins/codex/scripts/codex-companion.mjs	CLI entry point; parses, normalizes, and validates --effort; builds request payload
plugins/codex/scripts/lib/codex.mjs	Client library; forwards effort field to Codex API
tests/commands.test.mjs	Documents accepted values and default behavior expectations
tests/runtime.test.mjs	Verifies effort flag propagation to app-server turn start

Summary

• The plugin accepts six specific effort values: none, minimal, low, medium, high, xhigh
• normalizeReasoningEffort in codex-companion.mjs handles validation and normalization with strict error handling
• Valid values propagate to the task request payload at line 490 of codex-companion.mjs
• The plugin omits the field entirely when --effort is not specified, deferring to Codex defaults
• The Codex service performs the actual reasoning effort adjustment; the plugin only validates and forwards

Frequently Asked Questions

What happens if I omit the --effort flag?

The plugin does not include an effort field in the API request. According to tests/commands.test.mjs, this lets Codex apply its own default—currently medium—as defined by the backend service.

Can I use custom effort values like turbo or maximum?

No. The plugin rejects any value outside the six supported identifiers. The normalizeReasoningEffort function throws an error listing the allowed options: none, minimal, low, medium, high, xhigh.

Is effort case-sensitive?

No. The normalization step converts input to lowercase, so --effort HIGH, --effort high, and --effort High all resolve to "high".

Where does the actual reasoning effort adjustment happen?

In the Codex backend service. The plugin's responsibility ends at validation and forwarding. The closed-source service maps the effort string to internal computational parameters like thinking passes or search depth.

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