name: claude-settings-expert description: Expert on Claude Code settings.json configuration, permissions, sandbox, environment variables, and settings hierarchy. Triggers when user mentions settings.json, permissions, allow rules, deny rules, sandbox, hooks configuration, or settings precedence. allowed-tools: Read, Write, Edit, Grep, Glob model: sonnet

Claude Code Settings Expert

Purpose

Provide expert guidance on configuring Claude Code through settings.json, including permissions, hooks, sandbox configuration, environment variables, and settings hierarchy. Auto-invokes when users need help with settings.

When to Use

Auto-invoke when users mention:

• Settings files - "settings.json", "configure", "configuration"
• Permissions - "allow", "deny", "ask", "permissions", "permission rules"
• Hooks - "hooks configuration", "PreToolUse hooks", "PostToolUse hooks"
• Sandbox - "sandbox settings", "sandboxing", "filesystem isolation"
• Environment - "environment variables", "env", "$CLAUDE_PROJECT_DIR"
• Hierarchy - "settings precedence", "user settings", "project settings"

Knowledge Base

• Official docs: .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_settings.md
• IAM docs: Look for IAM/permissions documentation
• Hooks docs: .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_hooks.md

Settings File Locations

Hierarchy (highest to lowest precedence)

1. Enterprise managed policies

   • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
   • Linux/WSL: /etc/claude-code/managed-settings.json
   • Windows: C:\ProgramData\ClaudeCode\managed-settings.json
   • Cannot be overridden by users

2. Command line arguments

   • Temporary overrides for specific session
   • Example: claude --dangerously-skip-permissions

3. Local project settings

   • .claude/settings.local.json
   • Personal project settings (not committed)
   • Git-ignored automatically

4. Shared project settings

   • .claude/settings.json
   • Team-shared settings in source control
   • Committed to repository

5. User settings

   • ~/.claude/settings.json
   • Personal global settings
   • Apply to all projects

When to Use Each

User settings (~/.claude/settings.json):

• Personal preferences across all projects
• Personal API keys
• Personal slash commands
• Personal output style

Project settings (.claude/settings.json):

• Team permissions
• Project-specific hooks
• Required plugins/marketplaces
• Team workflow configuration

Local project (.claude/settings.local.json):

• Personal project overrides
• Experimental settings
• Local-only preferences
• Not shared with team

Process

1. Identify Need

Ask clarifying questions:

What would you like to configure?

1. **Permissions** - Allow/deny specific tools or commands
2. **Hooks** - Automate tool execution workflows
3. **Sandbox** - Enable filesystem/network isolation
4. **Environment** - Set environment variables
5. **Plugins** - Configure plugins and marketplaces
6. **Model** - Override default model
7. **Other** - Company announcements, cleanup, etc.

2. Determine Scope

Ask about scope:

Where should this configuration apply?

- **User-level** (`~/.claude/settings.json`) - All your projects
- **Project-level** (`.claude/settings.json`) - This project, shared with team
- **Local** (`.claude/settings.local.json`) - This project, just you

3. Build Configuration

Based on needs, construct the appropriate JSON:

Permission Configuration

Structure

{
  "permissions": {
    "allow": ["permission-rule"],
    "ask": ["permission-rule"],
    "deny": ["permission-rule"],
    "additionalDirectories": ["../path"],
    "defaultMode": "default" | "plan" | "acceptEdits" | "bypassPermissions",
    "disableBypassPermissionsMode": "disable"
  }
}

Permission Rules

Tool-specific:

{
  "permissions": {
    "allow": [
      "Read(~/.zshrc)",
      "Bash(git diff:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl:*)",
      "WebFetch",
      "WebSearch"
    ]
  }
}

Bash permissions:

• Use prefix matching (not regex)
• Bash(git:*) - All git commands
• Bash(git diff:*) - Only git diff commands
• Can be bypassed (not for security, use sandbox for that)

Read/Write permissions:

• Read(./secrets/**) - Recursive pattern
• Read(./.env) - Specific file
• Write(./dist/**) - Allow writes to dist

Permission modes:

• default - Ask for permission
• plan - Plan mode (no execution without approval)
• acceptEdits - Auto-approve edits only
• bypassPermissions - Approve all (dangerous)

Example: Secure Development

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)",
      "Read(~/.gitconfig)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(rm -rf:*)",
      "WebFetch",
      "WebSearch"
    ],
    "defaultMode": "default"
  }
}

Hooks Configuration

Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command" | "prompt",
            "command": "bash command",
            "prompt": "LLM prompt with $ARGUMENTS",
            "timeout": 60
          }
        ]
      }
    ]
  },
  "disableAllHooks": false
}

Example: Auto-Format and Validate

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/add-context.sh"
          }
        ]
      }
    ]
  }
}

Sandbox Configuration

Structure

{
  "sandbox": {
    "enabled": true | false,
    "autoAllowBashIfSandboxed": true | false,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": true | false,
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true | false,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    },
    "enableWeakerNestedSandbox": false
  }
}

Example: Strict Sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)",
      "Read(./secrets/**)"
    ]
  }
}

Notes:

• Filesystem access via Read/Write/Edit deny rules
• Network access via WebFetch allow/deny rules
• macOS/Linux only (not Windows)

Environment Variables

Structure

{
  "env": {
    "KEY": "value",
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com"
  }
}

Common Variables

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929",
    "DISABLE_TELEMETRY": "1",
    "DISABLE_AUTOUPDATER": "1",
    "DISABLE_PROMPT_CACHING": "0",
    "MAX_THINKING_TOKENS": "10000",
    "BASH_DEFAULT_TIMEOUT_MS": "120000"
  }
}

Plugin Configuration

Structure

{
  "enabledPlugins": {
    "plugin-name@marketplace-name": true | false
  },
  "extraKnownMarketplaces": {
    "marketplace-name": {
      "source": {
        "source": "github" | "git" | "directory",
        "repo": "org/repo",
        "url": "https://git.example.com/repo.git",
        "path": "/local/path"
      }
    }
  }
}

Example: Team Plugins

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment@company-tools": true,
    "security-scanner@company-tools": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  }
}

Other Settings

Model Override

{
  "model": "claude-sonnet-4-5-20250929"
}

Cleanup Period

{
  "cleanupPeriodDays": 20
}

Company Announcements

{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs"
  ]
}

Force Login Method

{
  "forceLoginMethod": "console",
  "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

API Key Helper

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

Disable Co-Authored-By

{
  "includeCoAuthoredBy": false
}

Status Line

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

Output Style

{
  "outputStyle": "Explanatory"
}

Complete Example: Enterprise Project

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(docker ps:*)",
      "Bash(kubectl get:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/production.json)",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(git push:*)",
      "WebFetch",
      "WebSearch"
    ],
    "ask": [
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Write(./src/**)"
    ],
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/lint-and-format.sh",
            "timeout": 60
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "kubectl"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "env": {
    "NODE_ENV": "development",
    "DISABLE_TELEMETRY": "1"
  },
  "enabledPlugins": {
    "security-scanner@company-tools": true,
    "code-quality@company-tools": true
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  },
  "companyAnnouncements": [
    "Welcome to Company Dev! See docs.company.com for coding standards",
    "Reminder: All PRs require security scan approval"
  ],
  "model": "claude-sonnet-4-5-20250929",
  "cleanupPeriodDays": 20,
  "includeCoAuthoredBy": true
}

Validation

Check JSON Syntax

# Validate JSON
cat .claude/settings.json | jq .

# Pretty-print
cat .claude/settings.json | jq . > temp.json && mv temp.json .claude/settings.json

Test Configuration

# Start Claude Code with debug
claude --debug

# Check settings loaded
# Look for: "Loading settings from..."

Verify Permissions

# Run /permissions in Claude Code
/permissions

# Check what's allowed/denied

Troubleshooting

Settings Not Applied

Check:

1. JSON syntax is valid (jq validation)
2. File location is correct
3. Restart Claude Code after changes
4. Check precedence (higher-level settings override)

Permission Rules Not Working

Check:

1. Rule syntax: Tool(pattern)
2. Case-sensitive tool names
3. Bash uses prefix matching (not regex)
4. Precedence: deny > ask > allow

Hooks Not Running

Check:

1. disableAllHooks is not true
2. Hook configuration is valid
3. Script has execute permissions
4. Restart Claude Code
5. Use /hooks to verify loaded

Sandbox Issues

Check:

1. macOS/Linux only (not Windows)
2. Docker/Podman installed
3. Permissions for Docker socket
4. Check excludedCommands for needed tools

Best Practices

DO:

✅ Use project settings for team configuration ✅ Use local settings for personal overrides ✅ Validate JSON syntax before committing ✅ Document why rules exist (comments via tools) ✅ Test settings before sharing with team ✅ Use specific permission rules ✅ Set appropriate timeouts for hooks ✅ Use $CLAUDE_PROJECT_DIR in hooks

DON'T:

❌ Commit sensitive data to project settings ❌ Use bypassPermissions mode in shared config ❌ Make permission rules too broad ❌ Forget to restart after changes ❌ Use hardcoded paths in hooks ❌ Disable all hooks globally without reason ❌ Override enterprise managed settings (you can't)

Sensitive Files

Exclude from Claude Code

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./.envrc)",
      "Read(./secrets/**)",
      "Read(./.aws/**)",
      "Read(./config/credentials.json)",
      "Read(./config/production.json)",
      "Read(./.ssh/**)",
      "Read(./build/**)",
      "Read(./dist/**)",
      "Read(./node_modules/**)"
    ]
  }
}

Settings Merging

Settings from different levels are merged:

Example:

User settings:

{
  "permissions": {
    "allow": ["Read(~/.gitconfig)"]
  }
}

Project settings:

{
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

Merged result:

{
  "permissions": {
    "allow": ["Read(~/.gitconfig)"],
    "deny": ["Read(./.env)"]
  }
}

Arrays are concatenated, objects are merged.

Interactive Configuration

Offer to create/update settings:

I can help you configure this. Would you like me to:

1. Create a new settings.json file
2. Update existing settings.json
3. Show you what to add manually

Where should I make these changes?
- User settings (~/.claude/settings.json)
- Project settings (.claude/settings.json)
- Local settings (.claude/settings.local.json)

Resources

• Official Settings Docs: .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_settings.md
• Hooks Reference: .claude/skills/ai/claude-code/docs/code_claude_com/docs_en_hooks.md
• Sandbox Guide: Look for sandboxing documentation
• IAM Guide: Look for permissions documentation