claude-code-settings
API reference · Repository · Issues
Claude Code's settings.json as Rust types.
Claude Code 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 and pass it to
claude --settings, or read settings files, layer them the way Claude Code
does, and write the result, without hand-built JSON.
Settingshas a field for every key in Claude Code's published JSON schema and its settings reference, with nested objects typed: permissions, hooks, the sandbox, marketplaces, plugin configuration, model settings and the rest.- Each field's docs say what Claude Code does with the key, the values it accepts, its default, where it may be set, and link to its entry in the settings reference.
- Keys, values, hook types and hook events the crate doesn't know are kept and written back unchanged, so a file from a newer Claude Code round-trips.
Settings::mergeapplies Claude Code's layer merge.- serde and serde_json only; no I/O.
This crate is not affiliated with or endorsed by Anthropic.
Install
Rust 1.85 or newer.
Quick start
Build a document and pass it to claude --settings. Every type is
#[non_exhaustive]: start from Default::default() and set fields. Only
what is set is written.
use ;
Read a settings file, change it, and write it back. Unknown keys and values survive:
use Settings;
How settings layer
Claude Code reads settings from several sources. Highest precedence first:
- Managed settings: what an organization deploys. Nothing below overrides a managed key.
- Command line:
--settings <file-or-json>, for one session. - Local project settings:
.claude/settings.local.json. - Shared project settings:
.claude/settings.json. - User settings:
~/.claude/settings.json.
It merges them instead of picking one:
- a scalar (string, number, Boolean) comes from the highest source that sets it;
- objects merge key by key (
env,permissions,sandbox, ...); - lists concatenate, so
permissions.allow/ask/denyand each hook event's matcher groups add up across sources;fallbackModelandmodelPickerare taken whole from the highest source.
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 a project can't set); each
field's Scope line says which, and the merge doesn't enforce it. Claude
Code 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 start.
Settings::merge applies one layer over another. Call it on the lowest
layer with each higher one in turn:
use Settings;
merge_values does the same on serde_json::Values.
Compatibility
| Claude Code | 2.1.322 (CLAUDE_CODE_VERSION) |
| JSON schema | fetched 2026-11-13 (SCHEMA_FETCHED) |
| Rust | 1.85 or newer |
The types follow two sources: the published JSON schema
(https://json.schemastore.org/claude-code-settings.json, a copy is in
schema/ in the repository) and Claude Code's settings reference, for the
keys the schema doesn't list yet. A document that sets every key is
checked against the Claude Code release above: it loads, and the only keys
skipped are the ones a --settings document may not set (managed-only
keys).
Releases:
- New keys and values are additive: the types are
#[non_exhaustive], so they ship as patch releases. An older release of this crate keeps a newer key inextra, so nothing is lost meanwhile. - A change that breaks the API (a key's type changes, a key is removed) bumps the minor version while the crate is 0.x.
- The changelog is
CHANGELOG.md; release-plz writes it and checks semver with cargo-semver-checks.
Keeping up with Claude Code
In the repository:
scripts/refresh-settings-schemafetches the schema again and records the date.- The
schematest (cargo test -p claude-code-settings) then fails, listing every property by JSON path (such assandbox.network.newOption, or$defs/hookCommand.newFieldfor a hook handler field) and every enum value the schema has that the types andtests/fixtures/full.jsondon't. Add each to its type and to the fixture. tests/cli.rshands the fixture to a realclaude --settings, offline, and fails on any key it rejects:CLAUDE_BIN=$(command -v claude) cargo test -p claude-code-settings --test cli -- --ignored. A weekly workflow runs it against the newest Claude Code.
Design notes
- Every key is an
Option, written only when set. One key keepsnullapart from absent:teammateDefaultModel, wherenullfollows the lead's model. - A value of the wrong type is an error, not dropped: Claude Code rejects the same document.
envis a plain map: its keys are environment variables, not settings.managedMcpServersentries and anmcp_toolhook'sinputstay JSON objects, as the schema leaves them open.- Marketplace and plugin sources are one struct,
Source:sourcenames the kind and the other fields are those the kind takes, so a new kind still parses. - Numbers the schema calls
numberaref64, so10is written back as10.0, the same JSON number. - Keys Claude Code accepts that neither the schema nor the settings
reference names, and the settings reference's "global config" keys,
which belong in
~/.claude.jsonrather thansettings.json, are left inextra.
License
Licensed under the Apache License, Version 2.0 (LICENSE).