settings-deep-dive

What this skill does

# Claude Code Settings Deep Dive

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

## Settings File Locations

| Location | Scope | Git Tracked |
|----------|-------|-------------|
| Managed (system-level) | Organization | `/Library/...` (macOS), `/etc/claude-code/` (Linux), `C:\Program Files\...` (Win) |
| `~/.claude/settings.json` | User (all projects) | N/A |
| `.claude/settings.json` | Project (shared) | Yes |
| `.claude/settings.local.json` | Project (personal) | No (gitignored) |

## Complete Settings Schema

```json
{
  // === 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 <[email protected]>",
    "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
```json
{
  "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
```json
{
  "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
| Pattern | Scope |
|---------|-------|
| `"Bash"` | Only Bash tool |
| `"Read"` | Only Read tool |
| `"Write"` | Only Write tool |
| `"Edit"` | Only Edit tool |
| `"Glob"` | Only Glob tool |
| `"Grep"` | Only Grep tool |
| `"WebFetch"` | Only WebFetch tool |
| `"Agent"` | Only Agent tool |
| `"mcp__*"` | All MCP tools |
| `"mcp__server__*"` | Specific MCP server |
| `"*"` | ALL tools |
| `""` | Default/all (for non-tool hooks) |

### Hook Script Interface

**Input (stdin):** JSON object

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

PostToolUse:
```json
{
  "tool_name": "string",
  "tool_input": { /* tool-s