claude_code_settings/models.rs
1//! `modelPicker`, `modelPricing` and `modelSettings`.
2
3use alloc::collections::BTreeMap;
4use alloc::string::String;
5use alloc::vec::Vec;
6
7use serde::{Deserialize, Serialize};
8
9use crate::Extra;
10use crate::enums::EffortLevel;
11use crate::walk::walk;
12
13/// `modelPicker`: the `/model` picker's rows.
14///
15/// List the models the `/model` picker offers, in the order you write them and under labels you
16/// choose, so the picker lists the models your organization runs, after the built-in lineup or
17/// instead of it. Each row's `model` is taken verbatim, so it accepts anything `--model`
18/// accepts: an alias such as `opus`, an Anthropic model ID, or a provider-format ID for Amazon
19/// Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or an LLM gateway.
20///
21/// Docs: [`modelPicker`](https://code.claude.com/docs/en/settings-reference#modelpicker).
22#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
23#[serde(rename_all = "camelCase")]
24#[non_exhaustive]
25pub struct ModelPicker {
26 /// The rows the picker shows, in this order, except that a grayed-out row moves to the
27 /// bottom. Without a `label`, Claude Code titles the row with the built-in name for a model
28 /// it knows, or the model ID otherwise, and without a `description` it writes a generic
29 /// second line.
30 ///
31 /// - **Values**: array of rows, each with a required `model` and optional `label`,
32 /// `description`, and `behavesAs`
33 /// - **Default**: unset
34 ///
35 /// Docs: [`options`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpicker).
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub options: Option<Vec<ModelPickerOption>>,
38 /// Set it to `true` to show only these rows, **Default**, and a row for the model the
39 /// session is already using. Leave it unset to add these rows after the built-in lineup.
40 ///
41 /// - **Values**: Boolean, default `false`
42 /// - **Default**: unset
43 ///
44 /// Docs: [`replaceBuiltInOptions`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpicker).
45 #[serde(skip_serializing_if = "Option::is_none")]
46 pub replace_built_in_options: Option<bool>,
47 /// Keys Claude Code accepts here that this crate doesn't model (newer or
48 /// undocumented ones), kept as written so the document round-trips.
49 #[serde(flatten)]
50 pub extra: Extra,
51}
52
53/// A row of `modelPicker.options`.
54///
55/// The rows the picker shows, in this order, except that a grayed-out row moves to the bottom.
56/// Without a `label`, Claude Code titles the row with the built-in name for a model it knows,
57/// or the model ID otherwise, and without a `description` it writes a generic second line.
58///
59/// Docs: [`modelPicker.options`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpicker).
60#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
61#[serde(rename_all = "camelCase")]
62#[non_exhaustive]
63pub struct ModelPickerOption {
64 /// The model the row selects, taken verbatim: anything `--model` accepts, such as an alias,
65 /// an Anthropic model ID, or a provider-format ID.
66 ///
67 /// - **Values**: string (required)
68 /// - **Default**: unset
69 ///
70 /// Docs: [`model`](None).
71 #[serde(skip_serializing_if = "Option::is_none")]
72 pub model: Option<String>,
73 /// The row's title. Without it, Claude Code uses the built-in name for a model it knows, or
74 /// the model ID.
75 ///
76 /// - **Values**: string
77 /// - **Default**: unset
78 ///
79 /// Docs: [`label`](None).
80 #[serde(skip_serializing_if = "Option::is_none")]
81 pub label: Option<String>,
82 /// The row's second line. Without it, Claude Code writes a generic one.
83 ///
84 /// - **Values**: string
85 /// - **Default**: unset
86 ///
87 /// Docs: [`description`](None).
88 #[serde(skip_serializing_if = "Option::is_none")]
89 pub description: Option<String>,
90 /// The ID of a model this Claude Code version knows, such as `claude-opus-4-8`, whose
91 /// capabilities and effort defaults apply to a newer `model`. Requires Claude Code v2.1.257
92 /// or later.
93 ///
94 /// - **Values**: string
95 /// - **Default**: unset
96 ///
97 /// Docs: [`behavesAs`](None).
98 #[serde(skip_serializing_if = "Option::is_none")]
99 pub behaves_as: Option<String>,
100 /// Keys Claude Code accepts here that this crate doesn't model (newer or
101 /// undocumented ones), kept as written so the document round-trips.
102 #[serde(flatten)]
103 pub extra: Extra,
104}
105
106/// `modelPricing`: contracted rates (managed settings).
107///
108/// Report spend at the rates your organization pays instead of list price. Set it when your
109/// organization has contracted rates, so the dollar figures developers see match your bill.
110///
111/// Docs: [`modelPricing`](https://code.claude.com/docs/en/settings-reference#modelpricing).
112#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
113#[serde(rename_all = "camelCase")]
114#[non_exhaustive]
115pub struct ModelPricing {
116 /// Scales every cost Claude Code computes, whether or not an `overrides` row covers it.
117 /// Below 1 is a discount, above 1 a markup.
118 ///
119 /// - **Values**: number greater than 0 and at most 10
120 /// - **Default**: unset
121 ///
122 /// Docs: [`multiplier`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpricing).
123 #[serde(skip_serializing_if = "Option::is_none")]
124 pub multiplier: Option<f64>,
125 /// The USD-per-million-token rates for that model, all four required. `cacheWrite` covers
126 /// both five-minute and one-hour cache writes. See [Which models a row applies
127 /// to](https://code.claude.com/docs/en/settings-reference#which-models-a-modelpricing-row-applies-to).
128 ///
129 /// - **Values**: map of model ID to a rate object with `input`, `output`, `cacheRead`, and
130 /// `cacheWrite`, each 0 to 10000
131 /// - **Default**: unset
132 ///
133 /// Docs: [`overrides`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpricing).
134 #[serde(skip_serializing_if = "Option::is_none")]
135 pub overrides: Option<BTreeMap<String, ModelRates>>,
136 /// Keys Claude Code accepts here that this crate doesn't model (newer or
137 /// undocumented ones), kept as written so the document round-trips.
138 #[serde(flatten)]
139 pub extra: Extra,
140}
141
142/// A model's rates, in USD per million tokens.
143///
144/// The USD-per-million-token rates for that model, all four required. `cacheWrite` covers both
145/// five-minute and one-hour cache writes.
146///
147/// Docs: [`modelPricing.overrides`](https://code.claude.com/docs/en/settings-reference#fields-for-modelpricing).
148#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
149#[serde(rename_all = "camelCase")]
150#[non_exhaustive]
151pub struct ModelRates {
152 /// The rate for input tokens.
153 ///
154 /// - **Values**: USD per million tokens, `0` to `10000`; all four rates are required
155 /// - **Default**: unset
156 ///
157 /// Docs: [`input`](None).
158 #[serde(skip_serializing_if = "Option::is_none")]
159 pub input: Option<f64>,
160 /// The rate for output tokens.
161 ///
162 /// - **Values**: USD per million tokens, `0` to `10000`; all four rates are required
163 /// - **Default**: unset
164 ///
165 /// Docs: [`output`](None).
166 #[serde(skip_serializing_if = "Option::is_none")]
167 pub output: Option<f64>,
168 /// The rate for cache reads.
169 ///
170 /// - **Values**: USD per million tokens, `0` to `10000`; all four rates are required
171 /// - **Default**: unset
172 ///
173 /// Docs: [`cacheRead`](None).
174 #[serde(skip_serializing_if = "Option::is_none")]
175 pub cache_read: Option<f64>,
176 /// The rate for cache writes, five-minute and one-hour alike.
177 ///
178 /// - **Values**: USD per million tokens, `0` to `10000`; all four rates are required
179 /// - **Default**: unset
180 ///
181 /// Docs: [`cacheWrite`](None).
182 #[serde(skip_serializing_if = "Option::is_none")]
183 pub cache_write: Option<f64>,
184 /// Keys Claude Code accepts here that this crate doesn't model (newer or
185 /// undocumented ones), kept as written so the document round-trips.
186 #[serde(flatten)]
187 pub extra: Extra,
188}
189
190/// A value of `modelSettings`: one model's saved settings.
191///
192/// Save an [effort level](https://code.claude.com/docs/en/model-config#adjust-effort-level) for
193/// each model you use. Requires Claude Code v2.1.251 or later.
194///
195/// Docs: [`modelSettings`](https://code.claude.com/docs/en/settings-reference#modelsettings).
196#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
197#[serde(rename_all = "camelCase")]
198#[non_exhaustive]
199pub struct ModelSettings {
200 /// This model's effort level. It takes precedence over the top-level `effortLevel` in the
201 /// same file.
202 ///
203 /// - **Values**: one of `"low"`, `"medium"`, `"high"`, or `"xhigh"`
204 /// - **Default**: unset
205 ///
206 /// Docs: [`effortLevel`](None).
207 #[serde(skip_serializing_if = "Option::is_none")]
208 pub effort_level: Option<EffortLevel>,
209 /// The highest effort level this model may run at. It replaces the top-level
210 /// `maxEffortLevel` for this model. Requires Claude Code v2.1.267 or later.
211 ///
212 /// - **Values**: one of `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"` (no cap)
213 /// - **Default**: unset
214 ///
215 /// Docs: [`maxEffortLevel`](None).
216 #[serde(skip_serializing_if = "Option::is_none")]
217 pub max_effort_level: Option<EffortLevel>,
218 /// This model's auto-compact window. It takes precedence over a top-level
219 /// `autoCompactWindow` in the same file; `/autocompact` saves here. Requires Claude Code
220 /// v2.1.288 or later.
221 ///
222 /// - **Values**: a number of tokens from `100000` to `1000000`, or `"auto"` for the window
223 /// tuned for the model
224 /// - **Default**: unset
225 ///
226 /// Docs: [`autoCompactWindow`](None).
227 #[serde(skip_serializing_if = "Option::is_none")]
228 pub auto_compact_window: Option<CompactWindow>,
229 /// Keys Claude Code accepts here that this crate doesn't model (newer or
230 /// undocumented ones), kept as written so the document round-trips.
231 #[serde(flatten)]
232 pub extra: Extra,
233}
234
235/// `modelSettings.*.autoCompactWindow`.
236#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
237#[serde(untagged)]
238#[non_exhaustive]
239pub enum CompactWindow {
240 /// A number of tokens (100 000 to 1 000 000).
241 Tokens(u64),
242 /// `auto`: the window tuned for the model.
243 Named(String),
244}
245
246walk!(ModelPicker { options: "options" });
247walk!(ModelPickerOption {});
248walk!(ModelPricing {
249 overrides: "overrides"
250});
251walk!(ModelRates {});
252walk!(ModelSettings {});