# Oh-My-Codex Team Model Resolution Precedence: Explicit vs Inherited vs Default

> Understand Oh-My-Codex team model resolution precedence. Explicit arguments override inherited settings and defaults for robust control.

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

---

**Oh-My-Codex resolves team worker models through a strict three-tier precedence chain where explicit launch arguments override inherited leader settings, which in turn override the low-complexity default fallback.**

The oh-my-codex framework orchestrates multi-agent teams using a deterministic model resolution system. Understanding the team model resolution precedence ensures workers execute with the intended LLM configuration across distributed computational tasks. This specification governs how each worker selects its inference model when operating within a team or swarm topology.

## The Three-Tier Precedence Hierarchy

According to [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 94‑100), the runtime evaluates three sources in descending priority order when determining which model a team worker should use.

### 1. Explicit Arguments via OMX_TEAM_WORKER_LAUNCH_ARGS

The highest priority source is the `OMX_TEAM_WORKER_LAUNCH_ARGS` environment variable. When this string contains a `--model <value>` flag, the system uses that value unconditionally, bypassing both leader inheritance and defaults.

This mechanism allows operators to force specific model versions for individual workers without affecting the broader team configuration. For example, assigning a high-capacity model to a single worker handling complex subtasks while others use standard resources.

### 2. Inherited Model from the Leader

When no explicit model flag exists in the worker's launch arguments, the worker inherits the `--model` value passed to the leader agent (the orchestrating process). This inheritance model maintains consistency across the team, ensuring all workers default to the leader's computational profile unless specifically overridden.

This approach simplifies configuration management, as setting the model once on the leader automatically propagates to all child workers in the swarm.

### 3. Low-Complexity Default Fallback

If neither explicit arguments nor leader inheritance provide a model, the runtime falls back to the default low-complexity model defined by `OMX_DEFAULT_SPARK_MODEL`. The system also recognizes the legacy alias `OMX_SPARK_MODEL` for backward compatibility.

As implemented in [`src/config/models.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts) (lines 66‑89), this fallback prioritizes fast, inexpensive models suitable for routine, low-complexity work, preventing accidental deployment of high-cost inference when no model is explicitly requested.

## Configuration Examples in Practice

### Override with Explicit Launch Arguments

Force a specific worker to use `gpt-5.4` regardless of leader settings:

```bash
OMX_TEAM_WORKER_LAUNCH_ARGS="--model gpt-5.4" omx team …

```

The worker executes with **gpt-5.4**, overriding any inherited or default configuration.

### Inherit from Leader Configuration

Start the leader with a high-capacity model and allow inheritance:

```bash
omx --model gpt-4.2 team …

```

With no explicit `OMX_TEAM_WORKER_LAUNCH_ARGS` set, all workers inherit **gpt-4.2** from the leader.

### Fallback to Low-Complexity Default

Deploy with no model specified on leader or workers:

```bash
export OMX_DEFAULT_SPARK_MODEL=gpt-5.3-codex-spark-fast
omx team …

```

Workers fall back to **gpt-5.3-codex-spark-fast**, the configured low-complexity default.

### Mixed Precedence Scenario

Combine all three tiers in a single deployment:

```bash
export OMX_DEFAULT_SPARK_MODEL=gpt-5.3-codex-spark-fast
omx --model gpt-4.1 team …

# Worker A: inherits gpt-4.1

OMX_TEAM_WORKER_LAUNCH_ARGS="--model gpt-5.4" omx team …

# Worker B: uses explicit gpt-5.4

```

- Worker A → **gpt‑4.1** (inherited from leader)
- Worker B → **gpt‑5.4** (explicit override)

## Source Code Implementation

The precedence logic is defined, implemented, and validated across three critical files:

- **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** (lines 94‑100): Documents the high-level specification for team model resolution.
- **[`src/config/models.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts)** (lines 66‑89): Implements default-model resolution logic, including `OMX_DEFAULT_SPARK_MODEL` handling and legacy alias support.
- **[`src/utils/__tests__/agents-model-table.test.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/utils/__tests__/agents-model-table.test.ts)**: Provides test coverage confirming the precedence chain operates correctly in production scenarios.

These files collectively enforce the contract that explicit arguments always win, inheritance serves as the middle tier, and low-complexity defaults provide the safety net.

## Summary

- **Explicit args rule**: `OMX_TEAM_WORKER_LAUNCH_ARGS` containing `--model` takes absolute precedence.
- **Inheritance is secondary**: Workers default to the leader's `--model` when no explicit argument exists.
- **Defaults are conservative**: `OMX_DEFAULT_SPARK_MODEL` (or `OMX_SPARK_MODEL`) provides a fast, low-cost fallback to prevent expensive accidental deployments.
- **Implementation spans three files**: Documentation in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), logic in [`src/config/models.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/config/models.ts), and verification in the agents model table test suite.

## Frequently Asked Questions

### What happens if I set both a leader model and explicit worker arguments?

The explicit worker arguments always win. According to the precedence defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), the system checks `OMX_TEAM_WORKER_LAUNCH_ARGS` first, so a `--model` flag there overrides whatever the leader specified.

### What is the difference between OMX_DEFAULT_SPARK_MODEL and OMX_SPARK_MODEL?

`OMX_DEFAULT_SPARK_MODEL` is the current canonical environment variable for the low-complexity default, while `OMX_SPARK_MODEL` serves as a legacy alias. Both variables configure the same fallback tier (tier 3), with the modern name taking precedence if both are present.

### Where is the team model resolution precedence officially documented?

The canonical specification resides in **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** at lines 94‑100, which explicitly lists the three-tier hierarchy: explicit launch args, inherited leader model, then low-complexity default.

### How can I verify the precedence logic is working correctly?

Review the test suite in **[`src/utils/__tests__/agents-model-table.test.ts`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/utils/__tests__/agents-model-table.test.ts)**, which validates the resolution order programmatically. You can also inspect the resolution chain at runtime by checking which model loads when varying `OMX_TEAM_WORKER_LAUNCH_ARGS` and leader flags.