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