Crate claude_settings 

Claude Settings

A Rust library for reading and writing Claude Code settings on Unix-like systems.

Overview

Claude Code uses a hierarchical settings system with multiple levels:

1. System (/etc/claude-code/managed-settings.json) - Read-only, highest priority
2. Project Local (.claude/settings.local.json) - Project-specific, not version controlled
3. Project (.claude/settings.json) - Project-specific, version controlled
4. User (~/.claude/settings.json) - User defaults, lowest priority

This library provides:

• Type-safe settings structures with serde serialization
• Read/write operations for each settings level
• Automatic path resolution based on project structure
• Settings merging with proper precedence handling

Quick Start

use claude_settings::{ClaudeSettings, Settings, SettingsLevel, PermissionSet};

// Create a settings manager
let manager = ClaudeSettings::new();

// Read user settings
if let Ok(Some(settings)) = manager.read(SettingsLevel::User) {
    println!("User model: {:?}", settings.model);
}

// Write project settings
let settings = Settings::new()
    .with_model("claude-sonnet-4-20250514")
    .with_permissions(
        PermissionSet::new()
            .allow("Bash(git:*)")
            .deny("Read(.env)")
    );

manager.write(SettingsLevel::Project, &settings).unwrap();

// Get effective settings (merged from all levels)
let effective = manager.effective().unwrap();

Settings Structure

The main Settings struct supports all Claude Code configuration options:

• permissions - Tool permission rules (allow/ask/deny)
• env - Environment variables for tool execution
• model - Override the default Claude model
• hooks - Pre/post tool execution hooks
• sandbox - Command sandboxing configuration
• attribution - Git commit/PR attribution messages
• enabled_plugins - Plugin enable/disable map
• cleanup_period_days - Session cleanup period
• language - Preferred response language

Structured Permissions

The permission module provides structured permission parsing and querying:

use claude_settings::permission::{Permission, PermissionSet, PermissionRule};

// Parse permission patterns
let perm = Permission::parse("Bash(git:*)").unwrap();
assert!(perm.matches("Bash", Some("git status")));

// Build a permission set
let set = PermissionSet::new()
    .allow(Permission::prefix("Bash", "git"))
    .deny(Permission::exact("Read", ".env"));

// Query permissions
assert_eq!(set.check("Bash", Some("git status")), PermissionRule::Allow);
assert_eq!(set.check("Read", Some(".env")), PermissionRule::Deny);

Figment Integration

Use merge::FigmentLoader for advanced configuration merging:

use claude_settings::merge::FigmentLoader;

let loader = FigmentLoader::with_defaults();
let settings = loader.load().unwrap();

Scoped Settings (Context Manager)

Use SettingsGuard for temporary modifications that auto-restore:

use claude_settings::{ClaudeSettings, SettingsLevel};

let manager = ClaudeSettings::new();

// Make temporary changes that auto-restore when guard drops
{
    let mut guard = manager.scoped(SettingsLevel::User)?;
    guard.set_model("temporary-model")
         .add_allow("Bash(rm:*)")
         .set_env("DEBUG", "1");
    guard.apply()?;

    // Changes are active here...
} // Original settings automatically restored

Re-exports

pub use error::Result;

pub use error::SettingsError;

pub use guard::MultiLevelGuard;

pub use guard::SettingsGuard;

pub use io::SettingsIO;

pub use merge::FigmentLoader;

pub use merge::Merge;

pub use merge::SettingsMerger;

pub use paths::PathResolver;

pub use permission::Permission;

pub use permission::PermissionPattern;

pub use permission::PermissionRule;

pub use permission::PermissionSet;

pub use types::Attribution;

pub use types::Hook;

pub use types::HookConfig;

pub use types::HookMatcher;

pub use types::Hooks;

pub use types::Permissions;

pub use types::Sandbox;

pub use types::Settings;

pub use types::SettingsLevel;

Modules

error

Error types for the Claude settings library.

guard

RAII guards for scoped settings mutations.

io

File I/O operations for Claude Code settings.

merge

Settings merging with precedence support.

paths

Path resolution for Claude Code settings files.

permission

Structured permission parsing, querying, and mutation.

types

Type definitions for Claude Code settings.

Structs

ClaudeSettings

High-level interface for managing Claude Code settings.