Settings Deep Dive

Claude Code Settings Deep Dive

Complete reference for every settings option, configuration key, and customization.

Settings File Locations

Complete Settings Schema

{
  // === PERMISSIONS ===
  "permissions": {
    "allow": ["Tool(pattern)"],
    "ask": ["Tool(pattern)"],
    "deny": ["Tool(pattern)"],
    "defaultMode": "default"
  },

  // === HOOKS ===
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ToolName",
        "hooks": [
          {
            "type": "command",
            "command": "bash script.sh",
            "timeout": 10000
          }
        ]
      }
    ],
    "PostToolUse": [],
    "Notification": [],
    "Stop": [],
    "SubagentStop": []
  },

  // === ENVIRONMENT ===
  "env": {
    "VARIABLE_NAME": "value"
  },

  // === MODEL ===
  "model": "claude-sonnet-4-6",
  "smallFastModel": "claude-haiku-4-5-20251001",

  // === BEHAVIOR ===
  "autoMemory": true,
  "autoCompact": true,
  "language": "en",
  "outputStyle": "Explanatory",
  "spinnerVerbs": true,
  "spinnerTipsEnabled": true,
  "showTurnDuration": false,
  "respectGitignore": true,
  "cleanupPeriodDays": 30,
  "fastModePerSessionOptIn": false,
  "autoUpdatesChannel": "stable",

  // === STATUS LINE ===
  "statusLine": {
    "enabled": true,
    "showModel": true,
    "showTokens": true,
    "showCost": true
  },

  // === FILE SUGGESTIONS ===
  "fileSuggestion": true,

  // === CONTEXT WINDOW ===
  "contextWindow": {
    "compactThreshold": 0.8,
    "warningThreshold": 0.9
  },

  // === MCP ===
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": [],
  "allowedMcpServers": [],

  // === SANDBOX ===
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["//tmp/build"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  },

  // === HOOKS ===
  "disableAllHooks": false,
  "allowManagedHooksOnly": false,
  "allowedHttpHookUrls": [],
  "httpHookAllowedEnvVars": [],

  // === AUTH & LOGIN ===
  "forceLoginMethod": null,

  // === PLUGINS ===
  "pluginTrustMessage": "",
  "extraKnownMarketplaces": [],
  "strictKnownMarketplaces": false,
  "blockedMarketplaces": [],

  // === CLAUDE.md ===
  "claudeMdExcludes": [],

  // === MODELS ===
  "availableModels": [],

  // === ATTRIBUTION ===
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  },
  "includeCoAuthoredBy": true, // DEPRECATED: use attribution instead

  // === CHANNELS (v2.1.80+) ===
  "channelsEnabled": true,       // Managed only - master switch for Team/Enterprise
  "allowedChannelPlugins": [     // Managed only - restrict which channel plugins
    { "marketplace": "claude-plugins-official", "plugin": "telegram" }
  ],

  // === AGENT TEAMS (experimental) ===
  "teammateMode": "auto",       // "auto" | "in-process" | "tmux"

  // === WORKTREE ===
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  },

  // === AUTO MODE ===
  "autoMode": {
    "environment": ["Trusted repo: github.example.com/acme"],
    "allow": ["Read any file in the project"],
    "soft_deny": ["Never delete production databases"]
  },
  "disableAutoMode": "disable",  // Set to "disable" to block auto mode; omit or remove key to allow
  "useAutoModeDuringPlan": true,

  // === EFFORT & VOICE ===
  "effortLevel": "high",        // "low" | "medium" | "high" (Opus 4.6, Sonnet 4.6)
  "voiceEnabled": false,
  "alwaysThinkingEnabled": false,

  // === UI CUSTOMIZATION ===
  "spinnerTipsOverride": {
    "excludeDefault": true,
    "tips": ["Use our internal tool X"]
  },
  "prefersReducedMotion": false,
  "terminalProgressBarEnabled": true,
  "showClearContextOnPlanAccept": false,
  "plansDirectory": "~/.claude/plans",

  // === MODELS ===
  "availableModels": ["sonnet", "haiku", "opus"],
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:..."
  }
}

Permissions Deep Dive

Tool Names

Read              — File reading
Write             — File creation/overwriting
Edit              — File modification
Glob              — File pattern search
Grep              — Content search
Bash              — Shell command execution
WebFetch          — Web content fetching
WebSearch         — Web searching
Agent             — Sub-agent spawning
TodoWrite         — Task tracking
NotebookEdit      — Jupyter notebook editing
AskUserQuestion   — User interaction (always allowed)
Skill             — Slash command invocation
ExitPlanMode      — Plan mode completion

Bash Pattern Matching

{
  "permissions": {
    "allow": [
      "Bash(npm test)",              // Exact match
      "Bash(npm run *)",             // npm run anything
      "Bash(npx *)",                 // Any npx command
      "Bash(git status)",            // Exact git status
      "Bash(git diff *)",            // git diff with any args
      "Bash(git log *)",             // git log with any args
      "Bash(git add *)",             // git add specific files
      "Bash(git commit *)",          // git commit
      "Bash(ls *)",                  // Any ls command
      "Bash(cat *)",                 // Any cat command
      "Bash(head *)",                // Any head command
      "Bash(tail *)",                // Any tail command
      "Bash(wc *)",                  // Word count
      "Bash(mkdir *)",               // Create directories
      "Bash(pwd)",                   // Print working directory
      "Bash(echo *)",                // Echo commands
      "Bash(which *)",               // Find executables
      "Bash(python3 *)",             // Python execution
      "Bash(node *)"                 // Node execution
    ],
    "deny": [
      "Bash(rm -rf /)",              // Block root delete
      "Bash(rm -rf ~)",              // Block home delete
      "Bash(sudo *)",                // Block sudo
      "Bash(chmod 777 *)",           // Block world-writable
      "Bash(curl * | sh)",           // Block pipe to shell
      "Bash(curl * | bash)",         // Block pipe to bash
      "Bash(wget * | sh)",           // Block wget pipe
      "Bash(eval *)",                // Block eval
      "Bash(> /dev/*)",              // Block device writes
      "Bash(dd *)"                   // Block disk operations
    ]
  }
}

MCP Tool Patterns

{
  "permissions": {
    "allow": [
      "mcp__filesystem__read_file",        // Specific tool
      "mcp__filesystem__list_directory",    // Specific tool
      "mcp__postgres__*",                   // All postgres tools
      "mcp__*"                              // All MCP tools
    ],
    "deny": [
      "mcp__filesystem__write_file",        // Block writes
      "mcp__filesystem__delete_file"        // Block deletes
    ]
  }
}

Hook Configuration Deep Dive

Matcher Patterns

Hook Script Interface

Input (stdin): JSON object

PreToolUse:

{
  "tool_name": "string",
  "tool_input": { /* tool-specific */ },
  "session_id": "string"
}

PostToolUse:

{
  "tool_name": "string",
  "tool_input": { /* tool-specific */ },
  "tool_output": { /* tool-specific */ },
  "session_id": "string"
}

Output (stdout): JSON object

PreToolUse responses:

{ "decision": "approve" }
{ "decision": "deny", "reason": "explanation" }
{ "decision": "approve", "tool_input": { /* modified input */ } }

Stop responses:

{ "decision": "stop" }
{ "decision": "continue", "message": "additional instructions" }

Hook Timeout

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash hook.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Environment Variables in Settings

{
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/mydb",
    "REDIS_URL": "redis://localhost:6379",
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug",
    "CUSTOM_API_KEY": "key-value"
  }
}

These env vars are available to:

• Bash tool commands
• Hook scripts
• MCP servers
• Any child processes

Local Overrides

.claude/settings.local.json — never committed to git:

{
  "permissions": {
    "allow": [
      "Bash(docker *)",
      "Bash(kubectl *)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/my_local_db",
    "ANTHROPIC_API_KEY": "sk-ant-my-personal-key"
  },
  "model": "claude-opus-4-6"
}

Merge Behavior

• permissions.allow: Arrays concatenated (local + project)
• permissions.deny: Arrays concatenated
• env: Objects deep-merged (local overrides project)
• model: Local overrides project
• hooks: Deep-merged (local hooks added to project hooks)

Feature Flags

{
  "autoMemory": true,          // Auto-save memories
  "autoCompact": true           // Auto-compact at threshold
}

Via Environment

DISABLE_AUTOMEMORY=1           # Disable auto-memory
DISABLE_BUG_COMMAND=1          # Disable /bug command
CLAUDE_CODE_SKIP_DOCTOR=1      # Skip doctor checks
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1  # Disable telemetry

Configuration Validation

Check Settings Syntax

python3 -c "
import json
try:
    data = json.load(open('.claude/settings.json'))
    print('Valid JSON')
    print('Keys:', list(data.keys()))
except json.JSONDecodeError as e:
    print(f'Invalid JSON: {e}')
"

Check MCP Config

python3 -c "
import json
try:
    data = json.load(open('.mcp.json'))
    for name, config in data.get('mcpServers', {}).items():
        cmd = config.get('command', 'N/A')
        disabled = config.get('disabled', False)
        status = 'DISABLED' if disabled else 'OK'
        print(f'  {name}: {cmd} [{status}]')
except Exception as e:
    print(f'Error: {e}')
"

Validate Plugin Manifests

python3 -c "
import json, glob
for f in glob.glob('plugins/*/. claude-plugin/plugin.json'):
    try:
        data = json.load(open(f))
        print(f'OK: {data[\"name\"]} v{data[\"version\"]}')
    except Exception as e:
        print(f'ERROR: {f}: {e}')
"

Common Settings Recipes

Developer Workstation

{
  "permissions": {
    "allow": [
      "Read", "Write", "Edit", "Glob", "Grep",
      "Bash(npm *)", "Bash(npx *)", "Bash(pnpm *)",
      "Bash(git *)", "Bash(ls *)", "Bash(cat *)",
      "Bash(mkdir *)", "Bash(node *)", "Bash(python3 *)",
      "WebFetch", "WebSearch", "Agent", "TodoWrite"
    ],
    "deny": [
      "Bash(rm -rf /)", "Bash(sudo *)"
    ]
  },
  "model": "claude-sonnet-4-6",
  "autoMemory": true,
  "autoCompact": true
}

CI/CD Pipeline

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Bash(npm test)", "Bash(npm run build)",
      "Bash(git diff *)", "Bash(git log *)"
    ],
    "deny": [
      "Write", "Edit",
      "Bash(git push *)", "Bash(git commit *)"
    ]
  },
  "model": "claude-haiku-4-5-20251001",
  "autoMemory": false
}

Attribution Customization

Default commit attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Default PR attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Custom Attribution (no Claude Code branding)

{
  "attribution": {
    "commit": "AI-assisted development\n\nCo-Authored-By: AI Assistant <ai@company.com>",
    "pr": "AI-assisted development"
  }
}

Hide All Attribution

{
  "attribution": {
    "commit": "",
    "pr": ""
  }
}

Inline Badge (shields.io)

{
  "attribution": {
    "commit": "",
    "pr": "[![Built by Markus](https://img.shields.io/badge/built%20by-Markus%20Ahling-ff6b35?style=for-the-badge&logo=github&logoColor=white)](https://github.com/markus41)"
  }
}

Channels Settings (v2.1.80+)

Channels push events into running sessions. Team/Enterprise require admin enablement.

Enable for Organization (Managed Settings)

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-ci-alerts" }
  ]
}

CLI Flags

# Start with channels
claude --channels plugin:telegram@claude-plugins-official

# Multiple channels
claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official

# Development channels (custom/local)
claude --dangerously-load-development-channels server:my-webhook

Agent Teams Settings (Experimental)

Enable

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

Display Modes

CLI Override

claude --teammate-mode in-process

Worktree Settings

Reduce disk usage and startup time in large monorepos:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

Settings Precedence

1. Managed (highest) — server-managed > MDM/plist > file-based > HKCU registry
2. Command line arguments — temporary session overrides
3. Local (.claude/settings.local.json) — personal project overrides
4. Project (.claude/settings.json) — team-shared settings
5. User (~/.claude/settings.json) — personal global (lowest)

Array settings (like permissions, sandbox paths) merge across scopes — they concatenate and deduplicate.

Security-Hardened

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep"
    ],
    "deny": [
      "Write", "Edit",
      "Bash(*)", "WebFetch", "WebSearch",
      "Agent", "mcp__*"
    ]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "bash .claude/hooks/audit-all.sh"
      }]
    }]
  }
}