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

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

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:

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:

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:

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 (lines 94‑100): Documents the high-level specification for team model resolution.
• 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: 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, logic in 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, 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 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, 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.

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