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

# Ok::<(), claude_settings::SettingsError>(())