Skip to main content

codex_codes/
models.rs

1//! Convenience enum for the models the Codex CLI exposes.
2//!
3//! Variants are keyed by human-friendly model names; [`CodexModel::cli_arg`]
4//! returns the model slug to pass to `codex -m` / `--model`, to
5//! `ThreadStartParams.model`, or to an `AppServerBuilder::config_override`
6//! of `model`.
7//!
8//! The catalog was taken from `openai/codex@main`'s bundled
9//! `models-manager/models.json` (2026-07-11). The server catalog evolves
10//! faster than this crate; GPT-6.1 Sol was verified against the live Codex
11//! catalog and official model documentation (2026-10-04); GPT-6-Sol and
12//! GPT-6-Luna were added from the bundled catalog at `openai/codex@d63a9b83`
13//! (2026-10-06); GPT-6.1 Terra from `openai/codex@126a0ee9` (2026-10-27);
14//! GPT-6.2-Sol and GPT-6.2-Astra from `openai/codex@6c0cee50` (2026-11-17).
15//! Unknown slugs round-trip through [`CodexModel::Custom`].
16
17use serde::{Deserialize, Deserializer, Serialize, Serializer};
18use std::fmt;
19
20/// A model slug accepted by the Codex CLI and app-server.
21#[derive(Debug, Clone, PartialEq, Eq, Hash)]
22pub enum CodexModel {
23    /// GPT-6.2-Sol (`gpt-6.2-sol`) — the catalog's fast, go-to model for
24    /// coding and everyday work. Availability depends on the server/account.
25    Gpt62Sol,
26    /// GPT-6.2-Astra (`gpt-6.2-astra`) — the catalog's most capable model for
27    /// complex coding and professional work. Availability depends on the
28    /// server/account.
29    Gpt62Astra,
30    /// GPT-6.1 Sol (`gpt-6.1-sol`). Availability depends on the server/account.
31    Gpt61Sol,
32    /// GPT-6.1 Terra (`gpt-6.1-terra`). Availability depends on the
33    /// server/account.
34    Gpt61Terra,
35    /// GPT-6-Astra (`gpt-6-astra`) — first GPT-6-family model in the
36    /// catalog (272k context). Live-probed 2026-09-04: the backend
37    /// recognizes the slug but rejects it for ChatGPT-plan auth
38    /// ("not supported when using Codex with a ChatGPT account").
39    Gpt6Astra,
40    /// GPT-6-Sol (`gpt-6-sol`). Availability depends on the server/account.
41    Gpt6Sol,
42    /// GPT-6-Luna (`gpt-6-luna`). Availability depends on the server/account.
43    Gpt6Luna,
44    /// Daybreak Blue (`gpt-daybreak-blue-latest`) — the cyber-access
45    /// program models (see `CyberAccessProgram`); server-side gated.
46    DaybreakBlue,
47    /// Daybreak Red (`gpt-daybreak-red-latest`) — cyber-access program,
48    /// 372k context; server-side gated.
49    DaybreakRed,
50    /// GPT-5.6-Sol (`gpt-5.6-sol`).
51    Gpt56Sol,
52    /// GPT-5.6-Terra (`gpt-5.6-terra`).
53    Gpt56Terra,
54    /// GPT-5.6-Luna (`gpt-5.6-luna`).
55    Gpt56Luna,
56    /// GPT-5.5 (`gpt-5.5`).
57    Gpt55,
58    /// GPT-5.4 (`gpt-5.4`).
59    Gpt54,
60    /// GPT-5.4-Mini (`gpt-5.4-mini`).
61    Gpt54Mini,
62    /// GPT-5.2 (`gpt-5.2`).
63    Gpt52,
64    /// Codex Auto Review (`codex-auto-review`) — hidden from the picker but
65    /// accepted by the API.
66    CodexAutoReview,
67    /// A model slug not yet known to this version of the crate. Passed
68    /// through verbatim.
69    Custom(String),
70}
71
72impl CodexModel {
73    /// The slug to pass to `codex -m` / `ThreadStartParams.model`.
74    pub fn cli_arg(&self) -> &str {
75        match self {
76            Self::Gpt62Sol => "gpt-6.2-sol",
77            Self::Gpt62Astra => "gpt-6.2-astra",
78            Self::Gpt61Sol => "gpt-6.1-sol",
79            Self::Gpt61Terra => "gpt-6.1-terra",
80            Self::Gpt6Astra => "gpt-6-astra",
81            Self::Gpt6Sol => "gpt-6-sol",
82            Self::Gpt6Luna => "gpt-6-luna",
83            Self::DaybreakBlue => "gpt-daybreak-blue-latest",
84            Self::DaybreakRed => "gpt-daybreak-red-latest",
85            Self::Gpt56Sol => "gpt-5.6-sol",
86            Self::Gpt56Terra => "gpt-5.6-terra",
87            Self::Gpt56Luna => "gpt-5.6-luna",
88            Self::Gpt55 => "gpt-5.5",
89            Self::Gpt54 => "gpt-5.4",
90            Self::Gpt54Mini => "gpt-5.4-mini",
91            Self::Gpt52 => "gpt-5.2",
92            Self::CodexAutoReview => "codex-auto-review",
93            Self::Custom(s) => s.as_str(),
94        }
95    }
96
97    /// Alias for [`cli_arg`](Self::cli_arg), matching the crate's string-enum
98    /// convention.
99    pub fn as_str(&self) -> &str {
100        self.cli_arg()
101    }
102
103    /// Human-friendly display name, matching the catalog's `display_name`.
104    pub fn display_name(&self) -> &str {
105        match self {
106            Self::Gpt62Sol => "GPT-6.2-Sol",
107            Self::Gpt62Astra => "GPT-6.2-Astra",
108            Self::Gpt61Sol => "GPT-6.1-Sol",
109            Self::Gpt61Terra => "GPT-6.1 Terra",
110            Self::Gpt6Astra => "GPT-6-Astra",
111            Self::Gpt6Sol => "GPT-6-Sol",
112            Self::Gpt6Luna => "GPT-6-Luna",
113            Self::DaybreakBlue => "Daybreak Blue",
114            Self::DaybreakRed => "Daybreak Red",
115            Self::Gpt56Sol => "GPT-5.6-Sol",
116            Self::Gpt56Terra => "GPT-5.6-Terra",
117            Self::Gpt56Luna => "GPT-5.6-Luna",
118            Self::Gpt55 => "GPT-5.5",
119            Self::Gpt54 => "GPT-5.4",
120            Self::Gpt54Mini => "GPT-5.4-Mini",
121            Self::Gpt52 => "GPT-5.2",
122            Self::CodexAutoReview => "Codex Auto Review",
123            Self::Custom(s) => s.as_str(),
124        }
125    }
126
127    /// Every model known to this version of the crate.
128    pub fn known() -> &'static [CodexModel] {
129        &[
130            Self::Gpt62Sol,
131            Self::Gpt62Astra,
132            Self::Gpt61Sol,
133            Self::Gpt61Terra,
134            Self::Gpt6Astra,
135            Self::Gpt6Sol,
136            Self::Gpt6Luna,
137            Self::DaybreakBlue,
138            Self::DaybreakRed,
139            Self::Gpt56Sol,
140            Self::Gpt56Terra,
141            Self::Gpt56Luna,
142            Self::Gpt55,
143            Self::Gpt54,
144            Self::Gpt54Mini,
145            Self::Gpt52,
146            Self::CodexAutoReview,
147        ]
148    }
149}
150
151impl fmt::Display for CodexModel {
152    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
153        f.write_str(self.cli_arg())
154    }
155}
156
157impl From<&str> for CodexModel {
158    fn from(s: &str) -> Self {
159        match s {
160            "gpt-6.2-sol" => Self::Gpt62Sol,
161            "gpt-6.2-astra" => Self::Gpt62Astra,
162            "gpt-6.1-sol" => Self::Gpt61Sol,
163            "gpt-6.1-terra" => Self::Gpt61Terra,
164            "gpt-6-astra" => Self::Gpt6Astra,
165            "gpt-6-sol" => Self::Gpt6Sol,
166            "gpt-6-luna" => Self::Gpt6Luna,
167            "gpt-daybreak-blue-latest" => Self::DaybreakBlue,
168            "gpt-daybreak-red-latest" => Self::DaybreakRed,
169            "gpt-5.6-sol" => Self::Gpt56Sol,
170            "gpt-5.6-terra" => Self::Gpt56Terra,
171            "gpt-5.6-luna" => Self::Gpt56Luna,
172            "gpt-5.5" => Self::Gpt55,
173            "gpt-5.4" => Self::Gpt54,
174            "gpt-5.4-mini" => Self::Gpt54Mini,
175            "gpt-5.2" => Self::Gpt52,
176            "codex-auto-review" => Self::CodexAutoReview,
177            other => Self::Custom(other.to_string()),
178        }
179    }
180}
181
182impl From<CodexModel> for String {
183    fn from(model: CodexModel) -> Self {
184        model.cli_arg().to_string()
185    }
186}
187
188impl Serialize for CodexModel {
189    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
190        serializer.serialize_str(self.cli_arg())
191    }
192}
193
194impl<'de> Deserialize<'de> for CodexModel {
195    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
196        let s = String::deserialize(deserializer)?;
197        Ok(Self::from(s.as_str()))
198    }
199}
200
201#[cfg(test)]
202mod tests {
203    use super::CodexModel;
204
205    #[test]
206    fn test_gpt61_sol_catalog_and_wire_round_trip() {
207        let model = CodexModel::from("gpt-6.1-sol");
208        assert_eq!(model, CodexModel::Gpt61Sol);
209        assert!(CodexModel::known().contains(&model));
210        assert_eq!(model.display_name(), "GPT-6.1-Sol");
211        assert_eq!(model.to_string(), "gpt-6.1-sol");
212        let json = serde_json::to_string(&model).unwrap();
213        assert_eq!(json, "\"gpt-6.1-sol\"");
214        assert_eq!(serde_json::from_str::<CodexModel>(&json).unwrap(), model);
215        let slug: String = model.into();
216        assert_eq!(slug, "gpt-6.1-sol");
217    }
218
219    #[test]
220    fn test_gpt6_family_catalog_entries() {
221        for (slug, model, label) in [
222            ("gpt-6-sol", CodexModel::Gpt6Sol, "GPT-6-Sol"),
223            ("gpt-6-luna", CodexModel::Gpt6Luna, "GPT-6-Luna"),
224            ("gpt-6.1-terra", CodexModel::Gpt61Terra, "GPT-6.1 Terra"),
225            ("gpt-6.2-sol", CodexModel::Gpt62Sol, "GPT-6.2-Sol"),
226            ("gpt-6.2-astra", CodexModel::Gpt62Astra, "GPT-6.2-Astra"),
227        ] {
228            assert_eq!(CodexModel::from(slug), model);
229            assert!(CodexModel::known().contains(&model));
230            assert_eq!(model.display_name(), label);
231            let json = serde_json::to_string(&model).unwrap();
232            assert_eq!(json, format!("\"{slug}\""));
233            assert_eq!(serde_json::from_str::<CodexModel>(&json).unwrap(), model);
234        }
235    }
236
237    #[test]
238    fn test_cli_arg_round_trip() {
239        for model in CodexModel::known() {
240            assert_eq!(&CodexModel::from(model.cli_arg()), model);
241        }
242        assert_eq!(
243            CodexModel::from("gpt-9-experimental"),
244            CodexModel::Custom("gpt-9-experimental".to_string())
245        );
246    }
247
248    #[test]
249    fn test_into_string_matches_cli_arg() {
250        let s: String = CodexModel::Gpt56Sol.into();
251        assert_eq!(s, "gpt-5.6-sol");
252    }
253
254    #[test]
255    fn test_converts_into_thread_start_model_field() {
256        // ThreadStartParams.model is Option<String>; the enum feeds it via Into.
257        let model: Option<String> = Some(CodexModel::Gpt55.into());
258        assert_eq!(model.as_deref(), Some("gpt-5.5"));
259    }
260
261    #[test]
262    fn test_serde_round_trip() {
263        let json = serde_json::to_string(&CodexModel::Gpt54Mini).unwrap();
264        assert_eq!(json, "\"gpt-5.4-mini\"");
265        let back: CodexModel = serde_json::from_str(&json).unwrap();
266        assert_eq!(back, CodexModel::Gpt54Mini);
267    }
268}