Skip to main content

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 {});