claude_code_settings/plugins.rs
1//! Plugins and marketplaces.
2
3use alloc::collections::BTreeMap;
4use alloc::string::String;
5use alloc::vec::Vec;
6
7use serde::{Deserialize, Serialize};
8use serde_json::Number;
9
10use crate::Extra;
11use crate::enums::{CustomizationKind, SourceKind};
12use crate::walk::{Unknown, walk};
13
14/// A value of `enabledPlugins`.
15#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
16#[serde(untagged)]
17#[non_exhaustive]
18pub enum PluginEnabled {
19 /// On or off.
20 Enabled(bool),
21 /// On, at these versions.
22 Versions(Vec<String>),
23}
24
25/// An entry of `extraKnownMarketplaces`.
26///
27/// Register additional plugin marketplaces by name, so that people who open the repository, or
28/// everyone your managed settings reach, get the marketplace without adding it themselves.
29/// Claude Code registers each marketplace it doesn't already know.
30///
31/// Docs: [`extraKnownMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces).
32#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
33#[serde(rename_all = "camelCase")]
34#[non_exhaustive]
35pub struct Marketplace {
36 /// Where to fetch the marketplace from.
37 ///
38 /// - **Values**: a marketplace source object: `source` names the kind (`github`, `git`,
39 /// `url`, `npm`, `file`, `directory`, `hostPattern`, `settings`), and the other fields
40 /// are the ones that kind takes
41 /// - **Default**: unset
42 ///
43 /// Docs: [`source`](None).
44 #[serde(skip_serializing_if = "Option::is_none")]
45 pub source: Option<Source>,
46 /// Local cache path where marketplace manifest is stored (auto-generated if not provided).
47 ///
48 /// - **Values**: string
49 /// - **Default**: unset
50 ///
51 /// Docs: [`installLocation`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces).
52 #[serde(skip_serializing_if = "Option::is_none")]
53 pub install_location: Option<String>,
54 /// Whether to automatically update this marketplace on Claude Code startup. Written
55 /// automatically by Claude Code when you toggle auto-update for a marketplace.
56 ///
57 /// - **Values**: Boolean
58 /// - **Default**: unset
59 ///
60 /// Docs: [`autoUpdate`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces).
61 #[serde(skip_serializing_if = "Option::is_none")]
62 pub auto_update: Option<bool>,
63 /// ISO 8601 timestamp of the last marketplace refresh. Written automatically by Claude
64 /// Code.
65 ///
66 /// - **Values**: string
67 /// - **Default**: unset
68 ///
69 /// Docs: [`lastUpdated`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces).
70 #[serde(skip_serializing_if = "Option::is_none")]
71 pub last_updated: Option<String>,
72 /// Keys Claude Code accepts here that this crate doesn't model (newer or
73 /// undocumented ones), kept as written so the document round-trips.
74 #[serde(flatten)]
75 pub extra: Extra,
76}
77
78/// A marketplace or plugin source: `source` names the kind, and the
79/// other fields are the ones that kind takes (`github`: `repo`, `ref`,
80/// `path`; `npm`: `package`; and so on). One struct for every kind, so a
81/// kind this crate doesn't know still parses.
82///
83/// Used by `extraKnownMarketplaces`, `strictKnownMarketplaces`,
84/// `blockedMarketplaces` and an inline marketplace's plugins.
85#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
86#[serde(rename_all = "camelCase")]
87#[non_exhaustive]
88pub struct Source {
89 /// Identifies the marketplace source type.
90 ///
91 /// - **Values**: string
92 /// - **Default**: unset
93 ///
94 /// Docs: [`source`](None).
95 #[serde(skip_serializing_if = "Option::is_none")]
96 pub source: Option<SourceKind>,
97 /// Direct URL to marketplace.json file.
98 ///
99 /// - **Values**: string
100 /// - **Default**: unset
101 ///
102 /// Docs: [`url`](None).
103 #[serde(skip_serializing_if = "Option::is_none")]
104 pub url: Option<String>,
105 /// GitHub repository in owner/repo format.
106 ///
107 /// - **Values**: string
108 /// - **Default**: unset
109 ///
110 /// Docs: [`repo`](None).
111 #[serde(skip_serializing_if = "Option::is_none")]
112 pub repo: Option<String>,
113 /// Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default
114 /// branch.
115 ///
116 /// - **Values**: string
117 /// - **Default**: unset
118 ///
119 /// Docs: [`ref`](None).
120 #[serde(rename = "ref", skip_serializing_if = "Option::is_none")]
121 pub git_ref: Option<String>,
122 /// A plugin source's exact commit SHA, which pins the plugin.
123 ///
124 /// - **Values**: string, a full commit SHA
125 /// - **Default**: unset
126 ///
127 /// Docs: [`sha`](None).
128 #[serde(skip_serializing_if = "Option::is_none")]
129 pub sha: Option<String>,
130 /// Path to marketplace.json within repo (defaults to .claude-plugin/marketplace.json).
131 ///
132 /// - **Values**: string
133 /// - **Default**: unset
134 ///
135 /// Docs: [`path`](None).
136 #[serde(skip_serializing_if = "Option::is_none")]
137 pub path: Option<String>,
138 /// Skip Git LFS downloads when Claude Code clones or updates the marketplace repository.
139 /// LFS pointer files remain as pointers instead of downloading their content. Use this when
140 /// the repository contains large LFS objects unrelated to plugin content.
141 ///
142 /// - **Values**: Boolean
143 /// - **Default**: unset
144 ///
145 /// Docs: [`skipLfs`](None).
146 #[serde(skip_serializing_if = "Option::is_none")]
147 pub skip_lfs: Option<bool>,
148 /// NPM package containing marketplace.json.
149 ///
150 /// - **Values**: string
151 /// - **Default**: unset
152 ///
153 /// Docs: [`package`](None).
154 #[serde(skip_serializing_if = "Option::is_none")]
155 pub package: Option<String>,
156 /// An `npm` plugin source's package version.
157 ///
158 /// - **Values**: string
159 /// - **Default**: unset
160 ///
161 /// Docs: [`version`](None).
162 #[serde(skip_serializing_if = "Option::is_none")]
163 pub version: Option<String>,
164 /// An `npm` plugin source's registry URL.
165 ///
166 /// - **Values**: string, a URL
167 /// - **Default**: unset
168 ///
169 /// Docs: [`registry`](None).
170 #[serde(skip_serializing_if = "Option::is_none")]
171 pub registry: Option<String>,
172 /// A `url` source's extra request headers, for authenticated access.
173 ///
174 /// - **Values**: object mapping header names to values
175 /// - **Default**: unset
176 ///
177 /// Docs: [`headers`](None).
178 #[serde(skip_serializing_if = "Option::is_none")]
179 pub headers: Option<BTreeMap<String, String>>,
180 /// A `url` source's command that prints headers whose values are too short-lived to list in
181 /// `headers`. Claude Code runs it before each fetch of the marketplace and each plugin
182 /// download from its origin, reusing its output for up to 60 seconds. Requires Claude Code
183 /// v2.1.238 or later.
184 ///
185 /// - **Values**: string, a command
186 /// - **Default**: unset
187 ///
188 /// Docs: [`headersHelper`](None).
189 #[serde(skip_serializing_if = "Option::is_none")]
190 pub headers_helper: Option<String>,
191 /// Git host pattern to trust for repositories in source specifications.
192 ///
193 /// - **Values**: string
194 /// - **Default**: unset
195 ///
196 /// Docs: [`hostPattern`](None).
197 #[serde(skip_serializing_if = "Option::is_none")]
198 pub host_pattern: Option<String>,
199 /// A `pathPattern` source (in `strictKnownMarketplaces` and `blockedMarketplaces`): a
200 /// regular expression matched against local marketplace paths.
201 ///
202 /// - **Values**: string, a regular expression
203 /// - **Default**: unset
204 ///
205 /// Docs: [`pathPattern`](None).
206 #[serde(skip_serializing_if = "Option::is_none")]
207 pub path_pattern: Option<String>,
208 /// Name of the inline marketplace.
209 ///
210 /// - **Values**: string
211 /// - **Default**: unset
212 ///
213 /// Docs: [`name`](None).
214 #[serde(skip_serializing_if = "Option::is_none")]
215 pub name: Option<String>,
216 /// Plugins declared inline. Each must reference an external source such as GitHub or npm.
217 /// You still need to enable each plugin separately in enabledPlugins.
218 ///
219 /// - **Values**: array of object
220 /// - **Default**: unset
221 ///
222 /// Docs: [`plugins`](None).
223 #[serde(skip_serializing_if = "Option::is_none")]
224 pub plugins: Option<Vec<InlinePlugin>>,
225 /// Keys Claude Code accepts here that this crate doesn't model (newer or
226 /// undocumented ones), kept as written so the document round-trips.
227 #[serde(flatten)]
228 pub extra: Extra,
229}
230
231impl Source {
232 /// A source of kind `kind` with no other field set.
233 pub fn new(kind: SourceKind) -> Self {
234 Self {
235 source: Some(kind),
236 ..Self::default()
237 }
238 }
239}
240
241/// A plugin of an inline (`settings`) marketplace.
242#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
243#[serde(rename_all = "camelCase")]
244#[non_exhaustive]
245pub struct InlinePlugin {
246 /// Plugin name.
247 ///
248 /// - **Values**: string
249 /// - **Default**: unset
250 ///
251 /// Docs: [`name`](None).
252 #[serde(skip_serializing_if = "Option::is_none")]
253 pub name: Option<String>,
254 /// External source the plugin is fetched from. Inline plugins must reference external
255 /// sources such as GitHub or npm, not relative paths.
256 ///
257 /// - **Values**: a plugin source object: `github`, `url`, `git-subdir` or `npm`
258 /// - **Default**: unset
259 ///
260 /// Docs: [`source`](None).
261 #[serde(skip_serializing_if = "Option::is_none")]
262 pub source: Option<Source>,
263 /// Keys Claude Code accepts here that this crate doesn't model (newer or
264 /// undocumented ones), kept as written so the document round-trips.
265 #[serde(flatten)]
266 pub extra: Extra,
267}
268
269/// An entry of `allowedChannelPlugins`.
270///
271/// Choose which [channel](https://code.claude.com/docs/en/channels) plugins can push messages
272/// into sessions in your organization. When you set it, Claude Code uses your list in place of
273/// the default Anthropic allowlist; each entry names a plugin and the marketplace it comes
274/// from.
275///
276/// Docs: [`allowedChannelPlugins`](https://code.claude.com/docs/en/settings-reference#allowedchannelplugins).
277#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
278#[serde(rename_all = "camelCase")]
279#[non_exhaustive]
280pub struct ChannelPlugin {
281 /// Name of the marketplace the channel plugin is installed from.
282 ///
283 /// - **Values**: string
284 /// - **Default**: unset
285 ///
286 /// Docs: [`marketplace`](https://code.claude.com/docs/en/settings-reference#allowedchannelplugins).
287 #[serde(skip_serializing_if = "Option::is_none")]
288 pub marketplace: Option<String>,
289 /// Name of the channel plugin allowed to run.
290 ///
291 /// - **Values**: string
292 /// - **Default**: unset
293 ///
294 /// Docs: [`plugin`](https://code.claude.com/docs/en/settings-reference#allowedchannelplugins).
295 #[serde(skip_serializing_if = "Option::is_none")]
296 pub plugin: Option<String>,
297 /// Keys Claude Code accepts here that this crate doesn't model (newer or
298 /// undocumented ones), kept as written so the document round-trips.
299 #[serde(flatten)]
300 pub extra: Extra,
301}
302
303/// An entry of `allowedChannelPlugins`.
304#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
305#[serde(untagged)]
306#[non_exhaustive]
307pub enum ChannelPluginEntry {
308 /// `plugin@marketplace`.
309 Id(String),
310 /// The object form.
311 Plugin(ChannelPlugin),
312}
313
314impl Unknown for ChannelPluginEntry {
315 fn unknown(&self, path: &str, out: &mut Vec<String>) {
316 if let Self::Plugin(p) = self {
317 p.unknown(path, out);
318 }
319 }
320}
321
322/// A value of `pluginConfigs`: a plugin's user configuration.
323///
324/// Store the non-sensitive answers you give a plugin's
325/// [`userConfig`](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)
326/// configuration dialog, keyed by plugin ID. Claude Code writes this key to your user settings
327/// when you fill in the dialog, so you don't need to edit it by hand. Claude Code stores
328/// sensitive options in the macOS Keychain instead, falling back to
329/// `~/.claude/.credentials.json` when the Keychain rejects the write; on platforms without a
330/// supported keychain, it stores them in `~/.claude/.credentials.json`.
331///
332/// Docs: [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs).
333#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
334#[serde(rename_all = "camelCase")]
335#[non_exhaustive]
336pub struct PluginConfig {
337 /// User configuration values for MCP servers keyed by server name.
338 ///
339 /// - **Values**: object
340 /// - **Default**: unset
341 ///
342 /// Docs: [`mcpServers`](https://code.claude.com/docs/en/settings-reference#pluginconfigs).
343 #[serde(skip_serializing_if = "Option::is_none")]
344 pub mcp_servers: Option<BTreeMap<String, BTreeMap<String, OptionValue>>>,
345 /// Non-sensitive option values from the plugin manifest's userConfig, keyed by option name.
346 /// Sensitive values go to secure storage instead.
347 ///
348 /// - **Values**: object
349 /// - **Default**: unset
350 ///
351 /// Docs: [`options`](https://code.claude.com/docs/en/settings-reference#pluginconfigs).
352 #[serde(skip_serializing_if = "Option::is_none")]
353 pub options: Option<BTreeMap<String, OptionValue>>,
354 /// Keys Claude Code accepts here that this crate doesn't model (newer or
355 /// undocumented ones), kept as written so the document round-trips.
356 #[serde(flatten)]
357 pub extra: Extra,
358}
359
360/// A plugin option's value.
361#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
362#[serde(untagged)]
363#[non_exhaustive]
364pub enum OptionValue {
365 /// A boolean.
366 Bool(bool),
367 /// A number.
368 Number(Number),
369 /// A string.
370 String(String),
371 /// A list of strings.
372 List(Vec<String>),
373}
374
375/// `strictPluginOnlyCustomization`.
376#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
377#[serde(untagged)]
378#[non_exhaustive]
379pub enum StrictCustomization {
380 /// Every kind (`true`) or none (`false`).
381 All(bool),
382 /// These kinds only.
383 Only(Vec<CustomizationKind>),
384}
385
386walk!(Marketplace { source: "source" });
387walk!(Source { plugins: "plugins" });
388walk!(InlinePlugin { source: "source" });
389walk!(ChannelPlugin {});
390walk!(PluginConfig {});