1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
//! Claude Code's `settings.json` as Rust types.
//!
//! [Claude Code](https://code.claude.com/docs) reads its configuration from
//! layered JSON settings files and from the `--settings` command-line
//! argument. This crate types every key those documents accept, so a
//! program can build one, write it for `claude --settings`, read settings
//! files, and layer them the way Claude Code does, without hand-built JSON.
//!
//! - [`Settings`]: the whole document. Every key Claude Code's published
//! JSON schema and its [settings reference] list is a field, with the
//! nested objects typed: [`Permissions`], [`Hooks`], [`Sandbox`],
//! marketplaces, plugin configuration, model settings and the rest. Each
//! field's docs say what Claude Code does with it, the values it accepts,
//! its default and where it may be set, with a link to its entry in the
//! settings reference.
//! - [`Settings::to_json_string`]: the document for `--settings`;
//! [`Settings::to_json_string_pretty`] for a file.
//! - [`Settings::merge`] and [`merge_values`]: Claude Code's layer merge.
//! - [`Settings::unknown_keys`]: the keys a document holds that this crate
//! doesn't model.
//!
//! The crate depends on serde and serde_json only, and does no I/O. It is
//! not affiliated with or endorsed by Anthropic.
//!
//! [settings reference]: https://code.claude.com/docs/en/settings-reference
//!
//! # Build a `--settings` document
//!
//! Every type is `#[non_exhaustive]`, so that Claude Code's new keys can be
//! added without a breaking release: start from `Default::default()` and
//! set fields. Only what is set is written.
//!
//! ```
//! use claude_code_settings::{Hook, HookEvent, HookMatcher, PermissionMode, Permissions, Settings};
//!
//! let mut permissions = Permissions::default();
//! permissions.allow = Some(vec!["Bash(git diff *)".into(), "Read".into()]);
//! permissions.deny = Some(vec!["Bash(rm *)".into()]);
//! permissions.default_mode = Some(PermissionMode::DontAsk);
//!
//! let mut settings = Settings::default();
//! settings.permissions = Some(permissions);
//! settings.include_git_instructions = Some(false);
//! settings.hooks.get_or_insert_default().insert(
//! HookEvent::PreToolUse,
//! vec![HookMatcher::matching("Bash", [Hook::command("./scripts/check-command")])],
//! );
//!
//! let arg = settings.to_json_string()?;
//! assert!(arg.contains(r#""defaultMode":"dontAsk""#));
//! // std::process::Command::new("claude").args(["--settings", &arg, "-p", "..."]);
//! # Ok::<(), serde_json::Error>(())
//! ```
//!
//! # Read a settings file, keeping what this crate doesn't know
//!
//! A key, an enum value, a hook type or a hook event this crate doesn't
//! model is kept as written (in an `extra` map, an `Other` variant or
//! [`Hook::Other`]) and written back unchanged, so a file from a newer
//! Claude Code survives a parse, a change and a write.
//!
//! ```
//! use claude_code_settings::{PermissionMode, Settings};
//!
//! let file = r#"{
//! "model": "opus",
//! "permissions": {"defaultMode": "someFutureMode", "allow": ["Read"]},
//! "aKeyFromANewerVersion": {"enabled": true}
//! }"#;
//! let mut settings = Settings::from_json_str(file)?;
//! assert_eq!(
//! settings.permissions.as_ref().and_then(|p| p.default_mode.clone()),
//! Some(PermissionMode::Other("someFutureMode".into())),
//! );
//! assert_eq!(settings.unknown_keys(), ["aKeyFromANewerVersion"]);
//!
//! settings.model = Some("sonnet".into());
//! let written = settings.to_json_string_pretty()?;
//! assert!(written.contains("aKeyFromANewerVersion"));
//! assert!(written.contains("someFutureMode"));
//! # Ok::<(), serde_json::Error>(())
//! ```
//!
//! # Layer settings
//!
//! Claude Code reads settings from several sources. Highest precedence
//! first:
//!
//! 1. **Managed settings**: what an organization deploys
//! (`managed-settings.json`, MDM, or server-managed settings). Nothing
//! below overrides a managed key.
//! 2. **Command line**: `--settings <file-or-json>`, for one session.
//! 3. **Local project settings**: `.claude/settings.local.json`.
//! 4. **Shared project settings**: `.claude/settings.json`.
//! 5. **User settings**: `~/.claude/settings.json`.
//!
//! Claude Code merges them rather than picking one:
//!
//! - a scalar (a string, number or Boolean) comes from the highest source
//! that sets it;
//! - objects merge key by key, so `env`, `permissions` and `sandbox`
//! combine across sources;
//! - lists concatenate, so `permissions.allow`, `ask` and `deny`, and each
//! hook event's matcher groups, add up; `fallbackModel` and
//! `modelPicker` are exceptions, taken whole from the highest source.
//!
//! Merging decides what each key holds, not how rules are applied: a
//! `deny` rule from any source beats an `allow` rule from any other
//! (Claude Code evaluates `deny`, then `ask`, then `allow`). Some keys are
//! honored only from some sources (managed-only keys, keys project settings
//! can't set), which each field's **Scope** line says and the merge does
//! not enforce. Claude Code also watches its settings files and reloads
//! most keys in a running session when a file changes; a few, such as
//! `model`, are read only at session start.
//!
//! [`Settings::merge`] applies one layer over another; call it on the
//! lowest layer with each higher one in turn:
//!
//! ```
//! use claude_code_settings::Settings;
//!
//! let user = Settings::from_json_str(r#"{
//! "model": "opus",
//! "env": {"EDITOR": "vim"},
//! "permissions": {"allow": ["Read"]}
//! }"#)?;
//! let project = Settings::from_json_str(r#"{
//! "model": "sonnet",
//! "env": {"RUST_LOG": "info"},
//! "permissions": {"allow": ["Bash(cargo test *)"], "deny": ["Bash(rm *)"]}
//! }"#)?;
//!
//! let mut effective = user;
//! effective.merge(project)?;
//! assert_eq!(effective.model.as_deref(), Some("sonnet"));
//! assert_eq!(effective.env.as_ref().map(|e| e.len()), Some(2));
//! let permissions = effective.permissions.unwrap_or_default();
//! assert_eq!(permissions.allow.unwrap_or_default(), ["Read", "Bash(cargo test *)"]);
//! assert_eq!(permissions.deny.unwrap_or_default(), ["Bash(rm *)"]);
//! # Ok::<(), serde_json::Error>(())
//! ```
//!
//! # Compatibility
//!
//! The types track [`CLAUDE_CODE_VERSION`] and the JSON schema fetched on
//! [`SCHEMA_FETCHED`]. A fully populated document is checked against that
//! Claude Code release: it loads with no key rejected. New keys and values
//! are additive: the types are `#[non_exhaustive]`, and an older release of
//! this crate keeps a newer key in `extra` rather than dropping it.
//!
//! # Keeping up with Claude Code
//!
//! The repository keeps a copy of the published schema
//! (<https://json.schemastore.org/claude-code-settings.json>) next to the
//! crate. `scripts/refresh-settings-schema` fetches it again, and the
//! crate's `schema` test then lists, by JSON path, every property and every
//! enum value the new schema has that the types don't. An opt-in test hands
//! a fully populated document to a real `claude --settings` and fails on any
//! key it rejects.
//!
//! # License
//!
//! Licensed under the Apache License, Version 2.0.
extern crate alloc;
pub use ;
pub use ;
pub use merge_values;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Settings;
pub use ;
/// The README's examples, compiled as doctests.
;
/// The Claude Code release these types were last checked against.
pub const CLAUDE_CODE_VERSION: &str = "2.1.322";
/// The date (UTC) the copy of the settings JSON schema these types follow
/// was fetched.
pub const SCHEMA_FETCHED: &str = "2026-11-13";
/// The keys an object holds that this crate doesn't model, by name.
pub type Extra = Map;