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

> Control oh-my-codex model selection with environment variables like OMX_DEFAULT_FRONTIER_MODEL and OMX_SPARK_MODEL. Customize LLM usage without code changes.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: how-to-guide
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts):

1. **Environment variable** (e.g., `export OMX_DEFAULT_FRONTIER_MODEL=gpt-5.4-mini`)
2. **[`.omx-config.json`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.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:

```bash

# 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:

```json
{
  "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:

```typescript
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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.omx-config.json) → built-in default.
- Configuration logic resides in [`src/config/models.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts) and is consumed by [`src/team/model-contract.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/.omx-config.json) entries exist, the framework uses the built-in constants defined at lines **65‑68** of [`src/config/models.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts): `gpt-5.4` for frontier, `gpt-5.4-mini` for standard, and `gpt-5.3-codex-spark` for spark workers.