Settings reference

This is the lookup page. When you already know roughly what you want to change and need the exact key, the values it accepts and where it is allowed to live, find the group below and scan the table. If you are still deciding which file to edit, or why a value is being ignored, start with Settings instead, which explains the file hierarchy and precedence.

I have grouped the keys by the job they do rather than alphabetically, because in practice you rarely touch one key in isolation: tightening permissions usually means touching three or four permission keys together, and turning on the sandbox means a whole sandbox block.

How to read the tables

Each table has a Where column that says which settings files are allowed to set the key. Claude Code silently ignores (or ignores with a warning) a key placed somewhere it does not accept.

A few conventions apply throughout:

• Unset means the key is absent. Many Boolean keys behave identically when unset and when set to their "on" value, so the only meaningful thing to write is false.
• Where a flag or environment variable can override a key for one session, I note it in the Notes column. The full list of variables lives on Environment variables and the flags on CLI reference.
• Several "kill switch" keys are one-way: once any file turns the feature off, no other file can turn it back on. I call these out where they apply.
• Version numbers such as "v2.1.267+" mean the key needs at least that Claude Code release.

Model and responses

These choose which model runs, how hard it thinks, and how the conversation is cached. For the bigger picture of aliases, effort and the /model picker, see Model configuration.

Effort per model

effortLevel is the blunt instrument; modelSettings lets each model keep its own level, and maxEffortLevel caps what any source can ask for. Here I let Opus run at xhigh for design work, keep Sonnet cheap, and cap everything else at high:

{
  "maxEffortLevel": "high",
  "modelSettings": {
    "claude-opus-5-5": { "effortLevel": "xhigh", "maxEffortLevel": "max" },
    "claude-sonnet-5": { "effortLevel": "medium", "autoCompactWindow": 400000 }
  }
}

Rules worth remembering:

• Inside one file, a model's own effortLevel beats the top-level one. Across files, the highest-precedence file that sets either form for that model decides.
• A per-model maxEffortLevel only replaces the top-level cap from the same source. Setting "max" exempts the model from that source's cap, not from caps in other files.
• autoCompactWindow inside modelSettings takes 100000 to 1000000 or "auto", and needs v2.1.288+.
• /effort auto clears the saved level for the current model.

modelPicker fields

Rows the session cannot serve are dropped; rows not yet selectable are greyed out and moved to the bottom; if nothing survives you get the built-in list back.

modelPricing fields

A row keyed by a built-in model ID also covers that model's dated and provider-specific IDs. Any other key (a gateway alias, say) matches that exact ID only.

Permissions

These keys decide what Claude can do unprompted. The concepts are covered in Permissions and Permission modes; this is the key list.

permissions.defaultMode values

Rule syntax in one minute

Rules are Tool or Tool(specifier). Deny is checked first, then ask, then allow, and the first match wins regardless of specificity. A small, realistic block for a Next.js repo:

{
  "permissions": {
    "allow": ["Bash(pnpm lint)", "Bash(pnpm test *)", "WebFetch(domain:nextjs.org)"],
    "ask": ["Bash(git push *)", "Bash(vercel *)"],
    "deny": ["Read(./.env.local)", "Read(./secrets/**)"],
    "defaultMode": "acceptEdits"
  }
}

In MCP rules, * may appear only in the tool part after mcp__<server>__, for example mcp__linear__list_*. The full grammar, including path anchors for Read and Edit, is on Permissions.

Sandbox

The sandbox object isolates Bash commands from your filesystem and network on macOS, Linux and WSL2. Read Sandboxing first; this section lists every key. Many keys carry extra limits when set from project or local files under an admin-required sandbox, which the sandboxing page explains.

Core switches

Filesystem

Path prefixes in these lists follow normal Unix conventions, which is the opposite of permission rules:

Trailing / and /** are stripped. Wildcards work in denyRead and allowRead on every platform, but in allowWrite and denyWrite they work only on macOS: on Linux and WSL2 an entry containing *, ? or [ is skipped.

Network

Credentials

sandbox.credentials hides or masks secrets that sandboxed commands would otherwise see. mask entries, allowPlaintextInject, awsPairs and sigv4 are honoured only from user settings, managed settings and --settings; mask entries in project or local files are dropped.

Optional fields on a mask entry:

An example I use for a Postgres connection string and a Stripe key, where the real values are only substituted on the way out to the right hosts:

{
  "sandbox": {
    "enabled": true,
    "network": { "allowedDomains": ["api.stripe.com", "db.internal.example"] },
    "credentials": {
      "envVars": [
        { "name": "DATABASE_URL", "mode": "mask", "extract": ":([^:@/]+)@", "onExtractNoMatch": "deny" },
        { "name": "STRIPE_SECRET_KEY", "mode": "mask", "injectHosts": ["api.stripe.com"] }
      ],
      "files": [{ "path": "~/.npmrc", "mode": "deny" }]
    }
  }
}

If a managed credential entry fails validation but still has a valid path or name, Claude Code degrades it to deny with a warning rather than dropping it.

Memory, context and environment

How env behaves

env looks simple but has sharp edges:

• A value here overrides the same variable exported in your shell. To cancel a shell export, set it to "".
• When the desktop app or a self-hosted environment runner launches the session, its launch environment wins over every env value.
• NO_COLOR and FORCE_COLOR set here reach subprocesses only, not Claude Code's own interface.
• User, managed and --settings values apply at startup; project and local values apply once you trust the workspace (or immediately in -p mode). A saved change to the merged env is picked up mid-session.
• Values are plain text in a file and reach every subprocess. Use apiKeyHelper or otelHeadersHelper for secrets instead.

Project and local files cannot set variables a cloned repository should not control. Claude Code drops these (logging a warning visible with claude --debug):

• Location variables: CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR, TMP, TEMP and the XDG_* family.
• Windows program and machine paths such as SystemRoot, ComSpec, ProgramData, LOCALAPPDATA, PATHEXT, PSModulePath and the ProgramFiles family.
• Variables that export session content, such as OTEL_LOG_RAW_API_BODIES, ENABLE_BETA_TRACING_DETAILED and BETA_TRACING_ENDPOINT.
• OpenTelemetry switches and destinations: CLAUDE_CODE_ENABLE_TELEMETRY, the enhanced telemetry beta pair, the OTEL_*_EXPORTER selectors, the OTEL_LOG_* content variables, OTEL_EXPORTER_OTLP_* endpoint, header, protocol and certificate variables, and the Prometheus host and port (v2.1.282+). Values that switch telemetry off, such as none for an exporter, still apply.
• Startup and sync variables such as CLAUDE_CODE_PROCESS_WRAPPER, CLAUDE_CODE_SYNC_SKILLS, CLAUDE_CODE_SYNC_PLUGINS, CLAUDE_CODE_PLUGIN_CACHE_DIR and CLAUDE_CODE_PLUGIN_SEED_DIR.

A handful are ignored from every settings file because only the launch environment may set them: hosting identity variables such as CLAUDE_CODE_REMOTE and CLAUDE_CODE_ACCOUNT_UUID, CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN, CLAUDE_CODE_PROJECT_DIR_NAME, CLAUDE_CODE_RESTRICTED, and the rm safety toggles (CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY, CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT, CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT, CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT).

Interface and terminal

Custom @ file suggestions

The command receives {"query": "..."} on stdin, gets the same environment as hooks (including CLAUDE_PROJECT_DIR), must answer within five seconds, and prints one path per line. Only the first 15 are shown. For a big monorepo I point it at git ls-files, which is faster than a filesystem walk:

#!/usr/bin/env bash
q=$(jq -r '.query')
git -C "$CLAUDE_PROJECT_DIR" ls-files | grep -i -- "$q" | head -15

{ "fileSuggestion": { "type": "command", "command": "~/.claude/bin/suggest-files.sh" } }

Footer link badges

Each footerLinksRegexes entry matches a regex against the finished turn's output and builds a link from named capture groups. Limits: the built URL must keep the template's literal origin, at most 2,048 characters; schemes are https, http or a known editor or app scheme (vscode, vscode-insiders, cursor, windsurf, zed, jetbrains, idea, slack, linear, notion, figma); labels are cut to 28 columns; at most five badges show, and /clear removes them. Keep patterns linear, because they run on the main thread.

{
  "footerLinksRegexes": [
    { "type": "regex", "pattern": "\\b(?<key>ENG-\\d+)\\b", "url": "https://linear.app/acme/issue/{key}", "label": "{key}" }
  ]
}

Custom spinner tips

Each tips entry is either a plain string or an object with id (required, up to 64 characters of letters, digits, ., _, -), text (required, one line, up to 500 characters), cooldownSessions (0 to 1000, default 0) and priority (-10 to 10, default 0). tipsFile points at a local JSON file of the same entries (up to 256 KB, read once per process, not deliverable through server-managed settings). label replaces the Tip prefix (up to 40 characters) and excludeDefault: true hides the built-in tips. Up to 200 tips are read. Project and local files may contribute plain strings only; the richer fields need v2.1.247+.

Git and attribution

Hooks and workflows

When allowManagedHooksOnly is on, or disableAllHooks is set outside managed settings, only a managed statusLine, subagentStatusLine or fileSuggestion runs; yours is skipped without warning.

Plugins, skills and marketplaces

Marketplace sources

Allowlists, blocklists and extraKnownMarketplaces describe marketplaces with a source object:

Allowlist matching is exact for github and git, including ref and path, so { "repo": "acme/plugins" } and { "repo": "acme/plugins", "ref": "main" } are different entries. Blocklists are looser: an entry without ref or path blocks all of them, and owner names compare case-insensitively.

MCP servers

Agents, sessions and worktrees

For a pnpm monorepo this saves me gigabytes of disk:

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules", ".turbo"],
    "sparsePaths": ["apps/web", "packages/ui", "packages/config"]
  }
}

Remote, desktop and notifications

Authentication and providers

Updates and versions

Desktop tools

Privacy and retention

Managed-only control keys

These shape how managed policy itself is delivered and combined. They only make sense in managed settings or server-managed settings.

Under "merge", keys combine by kind:

Only use "merge" when every lower-ranked source is also under admin control, because lower sources can then add allow rules. Run /status and check the "Setting sources" line to see what combined.

Global config keys (~/.claude.json)

These live in ~/.claude.json and are ignored in any settings file. /config writes most of them.

Older versions also kept theme, verbose, showTurnDuration, terminalProgressBarEnabled, teammateMode, preferredNotifChannel, remoteControlAtStartup, agentPushNotifEnabled, inputNeededNotifEnabled and respectGitignore here. Claude Code still reads those old values when no settings file sets the key.

Deprecated and removed keys

Related

• Settings: which file to edit and how precedence works
• Example settings files: complete personal, team and organisation files
• Permissions: rule syntax and evaluation order
• Sandboxing: what the sandbox keys actually enforce
• Environment variables: the per-session overrides mentioned throughout