claude-code-settings 0.1.0

Typed Claude Code settings.json: every key, lossless round-trips, and Claude Code's layer merge
Documentation
  • Coverage
  • 100%
    764 out of 764 items documented2 out of 2 items with examples
  • Size
  • Source code size: 427.5 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 7.6 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 10s Average build duration of successful builds.
  • all releases: 10s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • talaagent/ccwire
    1 0 5
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • macalinao

claude-code-settings

crates.io docs.rs CI License: Apache-2.0

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.

  • Settings has 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::merge applies Claude Code's layer merge.
  • serde and serde_json only; no I/O.

This crate is not affiliated with or endorsed by Anthropic.

Install

cargo add claude-code-settings

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 claude_code_settings::{Hook, HookEvent, HookMatcher, PermissionMode, Permissions, Settings};

fn main() -> Result<(), serde_json::Error> {
    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.hooks.get_or_insert_default().insert(
        HookEvent::PreToolUse,
        vec![HookMatcher::matching("Bash", [Hook::command("./scripts/check-command")])],
    );

    let arg = settings.to_json_string()?;
    // std::process::Command::new("claude").args(["--settings", &arg, "-p", "..."]);
    assert!(arg.contains(r#""defaultMode":"dontAsk""#));
    Ok(())
}

Read a settings file, change it, and write it back. Unknown keys and values survive:

use claude_code_settings::Settings;

fn main() -> Result<(), serde_json::Error> {
    let file = r#"{"model": "opus", "aKeyFromANewerVersion": {"enabled": true}}"#;
    let mut settings = Settings::from_json_str(file)?;
    assert_eq!(settings.unknown_keys(), ["aKeyFromANewerVersion"]);

    settings.model = Some("sonnet".into());
    let written = settings.to_json_string_pretty()?;
    assert!(written.contains("aKeyFromANewerVersion"));
    Ok(())
}

How settings layer

Claude Code reads settings from several sources. Highest precedence first:

  1. Managed settings: what an organization deploys. 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.

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/deny and each hook event's matcher groups add up across sources; fallbackModel and modelPicker are 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 claude_code_settings::Settings;

fn main() -> Result<(), serde_json::Error> {
    let user = Settings::from_json_str(r#"{"model": "opus", "permissions": {"allow": ["Read"]}}"#)?;
    let project = Settings::from_json_str(
        r#"{"model": "sonnet", "permissions": {"allow": ["Bash(cargo test *)"]}}"#,
    )?;

    let mut effective = user;
    effective.merge(project)?;
    assert_eq!(effective.model.as_deref(), Some("sonnet"));
    let allow = effective.permissions.unwrap_or_default().allow.unwrap_or_default();
    assert_eq!(allow, ["Read", "Bash(cargo test *)"]);
    Ok(())
}

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 in extra, 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-schema fetches the schema again and records the date.
  • The schema test (cargo test -p claude-code-settings) then fails, listing every property by JSON path (such as sandbox.network.newOption, or $defs/hookCommand.newField for a hook handler field) and every enum value the schema has that the types and tests/fixtures/full.json don't. Add each to its type and to the fixture.
  • tests/cli.rs hands the fixture to a real claude --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 keeps null apart from absent: teammateDefaultModel, where null follows the lead's model.
  • A value of the wrong type is an error, not dropped: Claude Code rejects the same document.
  • env is a plain map: its keys are environment variables, not settings. managedMcpServers entries and an mcp_tool hook's input stay JSON objects, as the schema leaves them open.
  • Marketplace and plugin sources are one struct, Source: source names the kind and the other fields are those the kind takes, so a new kind still parses.
  • Numbers the schema calls number are f64, so 10 is written back as 10.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.json rather than settings.json, are left in extra.

License

Licensed under the Apache License, Version 2.0 (LICENSE).