oh-my-codex Environment Variables: How OMX_DEFAULT_FRONTIER_MODEL and OMX_SPARK_MODEL Control Model Selection

Set OMX_DEFAULT_FRONTIER_MODEL, OMX_DEFAULT_STANDARD_MODEL, or OMX_DEFAULT_SPARK_MODEL to override which LLM oh-my-codex uses for frontier, standard, and spark agent workers without modifying code.

The oh-my-codex framework determines which language model powers each agent through a hierarchy of environment variables defined in src/config/models.ts. These variables allow you to steer high-complexity frontier agents, standard sub-agents, and low-complexity spark workers toward specific models across your entire session.

The Three Model Configuration Tiers

The source code declares three canonical slots for model selection at lines 39‑44 of src/config/models.ts. Each slot maps to a specific environment variable that overrides the built-in defaults.

Frontier Model (OMX_DEFAULT_FRONTIER_MODEL)

The frontier model serves as the main default for high-complexity agents. When you set OMX_DEFAULT_FRONTIER_MODEL, you override the default gpt-5.4 defined at lines 65‑68. This variable feeds the getMainDefaultModel() helper (lines 137‑140), which the agent-model contract consumes in src/team/model-contract.ts to resolve models for the executor role.

Standard Model (OMX_DEFAULT_STANDARD_MODEL)

The standard model acts as the fallback for standard sub-agents such as explore and executor when they request a standard tier. Configure this via OMX_DEFAULT_STANDARD_MODEL to replace the default gpt-5.4-mini. The resolution logic lives in getStandardDefaultModel() at lines 146‑148, which checks the environment variable before falling back to DEFAULT_STANDARD_MODEL.

Spark Model (OMX_DEFAULT_SPARK_MODEL and Legacy OMX_SPARK_MODEL)

The spark model targets low-complexity workers and the team low-complexity worker type. The canonical variable is OMX_DEFAULT_SPARK_MODEL, which supersedes the legacy alias OMX_SPARK_MODEL preserved for backward compatibility. The resolution chain—implemented at lines 72‑75 and 174‑179—checks the canonical name first, then the legacy alias, then the config file, and finally defaults to gpt-5.3-codex-spark.

Configuration Resolution Order

Each variable follows a strict precedence hierarchy documented in src/config/models.ts:

1. Environment variable (e.g., export OMX_DEFAULT_FRONTIER_MODEL=gpt-5.4-mini)
2. .omx-config.json env key (read by readConfigEnvValue() at lines 75‑80)
3. Built-in default constant (defined at lines 65‑68)

For the spark model specifically, the algorithm at lines 124‑130 first inspects OMX_DEFAULT_SPARK_MODEL, then falls back to the legacy OMX_SPARK_MODEL before checking the config file.

Configuring oh-my-codex Environment Variables

Shell Session Overrides

Set variables in your shell to affect all subsequent omx commands in that session:

# Override the frontier model for high-complexity agents

export OMX_DEFAULT_FRONTIER_MODEL=gpt-5.4-mini-tuned

# Override the spark model using the legacy alias

export OMX_SPARK_MODEL=gpt-5.3-codex-spark-fast

# Run commands—the framework now uses the overridden models

omx explore "Refactor this Python class"
omx team --mode low-complexity "Summarize the codebase"

The explore command internally calls getMainDefaultModel(), which extracts the value from process.env.OMX_DEFAULT_FRONTIER_MODEL (lines 137‑140).

Persistent Configuration with .omx-config.json

Persist overrides in a repository root file to avoid exporting variables in every shell:

{
  "env": {
    "OMX_DEFAULT_FRONTIER_MODEL": "gpt-5.4-mini",
    "OMX_DEFAULT_STANDARD_MODEL": "gpt-5.4-mini",
    "OMX_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
  }
}

When environment variables are unset, readConfigEnvValue() (lines 75‑80) reads this JSON and supplies the values, ensuring fresh shells inherit the same defaults.

Programmatic Access

Query the resolved models directly in TypeScript to verify configuration:

import { 
  getMainDefaultModel, 
  getStandardDefaultModel, 
  getSparkDefaultModel 
} from './src/config/models.js';

console.log('Frontier →', getMainDefaultModel());      // e.g., "gpt-5.4-mini-tuned"
console.log('Standard →', getStandardDefaultModel());  // e.g., "gpt-5.4-mini"
console.log('Spark →', getSparkDefaultModel());      // e.g., "gpt-5.3-codex-spark"

These functions expose the exact resolution logic used by the runtime, matching the precedence rules defined in the source.

Runtime Consumption of Model Variables

The resolved environment variables flow through specific integration points:

• src/team/model-contract.ts consumes getMainDefaultModel() at lines 179‑185 to bind the frontier model to the executor agent role.
• src/cli/explore.ts injects the main default model as a fallback at lines 341‑342 when invoking the underlying model runner.

By setting any of these three variables—or their equivalents inside .omx-config.json—you directly steer which model the framework picks for each class of agent without touching the underlying source code.

Summary

• OMX_DEFAULT_FRONTIER_MODEL controls the main model for high-complexity frontier agents (default: gpt-5.4).
• OMX_DEFAULT_STANDARD_MODEL controls the fallback for standard sub-agents (default: gpt-5.4-mini).
• OMX_DEFAULT_SPARK_MODEL controls low-complexity spark workers, with legacy support for OMX_SPARK_MODEL (default: gpt-5.3-codex-spark).
• Resolution follows a strict order: environment variable → .omx-config.json → built-in default.
• Configuration logic resides in src/config/models.ts and is consumed by src/team/model-contract.ts and CLI commands like explore.

Frequently Asked Questions

What is the difference between OMX_DEFAULT_FRONTIER_MODEL and OMX_DEFAULT_SPARK_MODEL?

OMX_DEFAULT_FRONTIER_MODEL selects the model for high-complexity agents that perform reasoning-heavy tasks, defaulting to gpt-5.4. OMX_DEFAULT_SPARK_MODEL selects the model for low-complexity or "spark" workers that handle lightweight operations, defaulting to gpt-5.3-codex-spark. The frontier model is typically larger and more capable, while the spark model is optimized for speed and cost.

Can I use .omx-config.json instead of environment variables?

Yes. Create a .omx-config.json file in your repository root with an "env" key containing any of the three variable names. When the shell environment lacks an explicit export, readConfigEnvValue() (lines 75‑80) reads this file and applies the values as if they were exported variables.

Does the legacy OMX_SPARK_MODEL variable still work?

Yes. The framework maintains backward compatibility for OMX_SPARK_MODEL. In getEnvConfiguredSparkDefaultModel() (lines 124‑130), the code first checks OMX_DEFAULT_SPARK_MODEL, then falls back to the legacy OMX_SPARK_MODEL if the canonical variable is unset. However, new configurations should use OMX_DEFAULT_SPARK_MODEL.

What are the default models if no environment variables are set?

If neither environment variables nor .omx-config.json entries exist, the framework uses the built-in constants defined at lines 65‑68 of src/config/models.ts: gpt-5.4 for frontier, gpt-5.4-mini for standard, and gpt-5.3-codex-spark for spark workers.

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