Claude Code settings.json: the six lines that matter

Inside a real Claude Code settings.json

~/.claude/settings.json holds your defaults — and everything in it does one of three jobs: deciding how Claude thinks (model, effort, extended thinking), deciding what runs without asking (permissions), and deleting friction you've resolved once and mean forever (confirmation screens, UI timers, voice). Here's the studio file this article walks through, unredacted because there's nothing secret in it:

{
  "permissions": {
    "defaultMode": "auto"
  },
  "model": "claude-fable-5[1m]",
  "enabledPlugins": {
    "code-review@claude-code-plugins": true,
    "commit-commands@claude-code-plugins": true,
    "feature-dev@claude-code-plugins": true,
    "pr-review-toolkit@claude-code-plugins": true,
    "security-guidance@claude-code-plugins": true,
    "swift-lsp@claude-plugins-official": true,
    "frontend-design@claude-plugins-official": true,
    "playwright@claude-plugins-official": true,
    "figma@claude-plugins-official": true,
    "docs-knowledge@local": true,
    "onda-shoot@local": true,
    "shopify-craft@local": true,
    "stripe@claude-plugins-official": true
  },
  "extraKnownMarketplaces": {
    "local": {
      "source": {
        "source": "directory",
        "path": "/Users/wavvey/.claude/plugins/marketplaces/local"
      }
    }
  },
  "alwaysThinkingEnabled": true,
  "effortLevel": "xhigh",
  "voice": {
    "enabled": true,
    "mode": "hold"
  },
  "skipDangerousModePermissionPrompt": true,
  "skipWorkflowUsageWarning": true,
  "autoCompactEnabled": false,
  "showTurnDuration": false,
  "agentPushNotifEnabled": true,
  "skipAutoPermissionPrompt": true,
  "voiceEnabled": true
}

Walk it by job. permissions.defaultMode: "auto" sets the autonomy rung every session starts on — permission modes are a whole topic of their own, so file that line and move on. model pins the daily driver instead of accepting whatever ships as default; the [1m] suffix requests the million-token context variant, which matters once Claude is holding a whole repo in its head. alwaysThinkingEnabled plus effortLevel: "xhigh" turn extended thinking on for every turn at maximum effort — slower and costlier per answer, in exchange for fewer shallow ones. That trade is right for a studio billing flat-rate on a Max subscription; on a tighter plan you might leave effort at its default.

enabledPlugins is the toolbelt, each key shaped name@marketplace: five plugins from the claude-code-plugins marketplace, four official, three from local, plus stripe. And local only resolves because extraKnownMarketplaces points it at a directory — ~/.claude/plugins/marketplaces/local — where the studio's own plugins live. The block above spells it /Users/wavvey/... because that's the literal home folder on that machine; one more reason this file is for reading, not wholesale pasting.

Everything else is friction removal. The three skip* flags retire are-you-sure screens that have been read once and meant forever. autoCompactEnabled: false stops automatic context compaction in favor of compacting deliberately, mid-session, at chosen moments. showTurnDuration: false hides the per-turn stopwatch. agentPushNotifEnabled: true pings when a long-running agent finishes. The voice block enables hold-to-talk dictation (voiceEnabled is the older blunt switch riding alongside it).

Start with six lines, not forty-two

Don't paste the studio file wholesale — its plugin list references marketplaces you haven't added, and its home-folder path isn't yours. The right starting point is six lines:

{
  "permissions": {
    "defaultMode": "default"
  },
  "alwaysThinkingEnabled": true
}

That starter is complete and valid as shown: a cautious permission default plus extended thinking. The cautious "defaultMode": "default" is deliberate — every edit and command prompts until you've decided, repo by repo, how much autonomy the workspace can afford, and it's one line to change later. From there, four steps prove the file is real and loaded:

1. 01Look at yours first: cat ~/.claude/settings.json. Fresh installs may not have one at all — that's normal; you're about to create it.
2. 02Create the file with the six-line core above, and grow it as each additional key earns its place.
3. 03Validate the JSON: jq . ~/.claude/settings.json either pretty-prints the file or names the exact line that's broken. A trailing comma is the classic.
4. 04See it land: start a fresh claude session and run /config — the live settings panel, showing what the tool actually loaded. If your file parsed, your values are in there.

For a quick structural check of any settings file, jq can also list its top-level keys. Here's the full studio file under that lens:

$ jq 'keys' ~/.claude/settings.json
[
  "agentPushNotifEnabled",
  "alwaysThinkingEnabled",
  "autoCompactEnabled",
  "effortLevel",
  "enabledPlugins",
  "extraKnownMarketplaces",
  "model",
  "permissions",
  "showTurnDuration",
  "skipAutoPermissionPrompt",
  "skipDangerousModePermissionPrompt",
  "skipWorkflowUsageWarning",
  "voice",
  "voiceEnabled"
]

One operational detail saves confusion later: a few settings — permissions and hooks among them — reload while a session is running, but most don't. model, for instance, is read at startup; mid-session you switch it with the /model command instead. When a settings edit seems to be ignored, restart the session before you debug the JSON.

The cascade: which file wins

Global settings are one layer of five. The cascade runs managed policy, then CLI flags, then the local project file, then the committed project file, then your user file — and when the same key appears in multiple layers, the first, more specific layer to define it wins:

A committed project file outranking your global taste is by design: the repo's caution travels through git, and only a CLI flag, your settings.local.json, or managed policy can override it. The complete key reference — dozens of settings beyond the fourteen here — plus precedence rules and file locations for every platform is in the settings docs.

If claude --version doesn't answer anything yet, the install comes first. And the six-line starter exists as a card deck at settings.json in six lines if you want the pocket version.