Last updated: 2026-10-30

Claude Code settings.json: Options That Actually Work

Claude Code's behaviour is set in settings.json files — permission rules, the default model, environment variables, and hooks that run on tool events. This page covers the options people most often reach for, checked against Claude Code's own documentation, plus the settings added in the most recent releases.

Correction, 2026-09-25

An earlier version of this page, titled "hidden configuration options not in the official docs", listed autoApprove, bash.allowedCommands, disableToolUseStreaming, and hooks named PreBash and PostEdit. None of those exist in Claude Code. They appear nowhere in its settings or hooks reference, and a settings file relying on them does nothing. The working equivalents are below. We're sorry for the bad information.

Where settings live

Claude Code reads project settings from .claude/settings.json and your user settings from ~/.claude/settings.json. Managed settings that an organisation deploys sit above both, and nothing you set overrides them. Claude Code watches these files and applies most edits — including permissions and hooks — to a running session without a restart. Add a "$schema" line pointing at https://json.schemastore.org/claude-code-settings.json and your editor will validate the file as you type.

Permission rules instead of approval prompts

To stop Claude Code asking before routine commands, add rules under permissions. Each rule names a tool and what it may do; deny rules block outright:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Bash(curl *)"
    ]
  }
}

The rule syntax is documented in Claude Code's permissions guide. Keep allow rules narrow — a broad Bash(*) hands over the whole shell.

Model and environment variables

model sets the default model for sessions that load the file — useful to pin a cost-sensitive project to a cheaper model. ANTHROPIC_MODEL in your shell overrides it, and --model overrides both for one session; /model switches mid-session.
env sets environment variables for Claude Code's session, such as NODE_ENV or a local API mock URL. Some variables, including most telemetry exports, are ignored when set in project or local settings.

Hooks: run a script on a tool event

Hooks attach commands to events such as PreToolUse and PostToolUse. A matcher picks which tools the hook applies to, and an optional if narrows it further:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

The script receives the event as JSON on stdin and can return a permissionDecision of "deny" to stop the call. This is how teams block destructive commands, run a linter after edits, or log every file Claude touches. The event list and input fields are in the hooks reference.

Sessions now start in auto mode (2.1.284–2.1.285)

Since 2.1.284, interactive terminal and VS Code sessions start in auto mode when no permission mode is configured, on every plan and provider. 2.1.285 extends that to claude -p and Python Agent SDK sessions on third-party providers or with telemetry off. A --permission-mode flag or permissions.defaultMode in a settings file overrides the built-in default. If you rely on the old prompt-first behaviour, or run unattended routines whose prompts assume it, set it explicitly:

{
  "permissions": {
    "defaultMode": "default"
  }
}

default is the mode the CLI labels Manual: it prompts on first use of each tool. Project-level .claude/settings.json honours every value except auto and bypassPermissions; set those in your user or managed settings instead. If auto mode isn't available to a session (a settings file turned it off, or the model doesn't support it), Claude Code starts in Manual. Source: Claude Code docs: which mode a session starts in.

Also new in 2.1.287–2.1.295 (checked 2026-10-09)

Hooks that fail closed (2.1.295). A command or HTTP hook with onFailure: "block" blocks the action when the hook can't start, times out or exits with an unexpected code, instead of letting it through. Since 2.1.294 a prompt hook on Stop or SubagentStop written as an instruction (such as "carry on if the build is broken") is judged so that Claude is less likely to stop early.
Claude apps gateway sign-in (2.1.295). forceLoginMethod: "gateway" and forceLoginGatewayUrl now work in your own user settings on a machine with no managed settings, so /login opens on that gateway.
Settings a repository can no longer set (2.1.290). CLAUDE_CODE_DISABLE_ATTACHMENTS is ignored in a repository's .claude/settings.json and settings.local.json (shell, user and managed settings still work), and a project's settings files can no longer turn on Claude in Chrome; use --chrome, /chrome or your user settings.
Retry controls. CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS (2.1.295) caps how long each request spends waiting out 429 and 529 errors in unattended retry mode; unset, the wait has no limit. CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS (2.1.292) raises the starting delay of the 529 backoff, up to 32000 (the default is 500). CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS (2.1.288) stops Claude Code sending the structured-output field to an LLM gateway whose upstream rejects it.
WebSearch refills (2.1.290). An interactive session's WebSearch limit now refills at 100 calls an hour instead of ending after 200 calls; CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR changes the rate (default 0 in non-interactive sessions, which turns refill off).
MCP. Setting alwaysLoad: false on a server defers all of its tools behind tool search (2.1.287). Local (stdio) servers negotiate MCP protocol 2026-07-28 by default on every install (2.1.292), and claude.ai connectors do on installs that fetch no feature flags (2.1.295); MCP_PROTOCOL_NEGOTIATION=legacy opts out of both. If a server stopped connecting after 2.1.287, add "bareElicitationCapability": true to its MCP config entry. Descriptions the model loads through tool search are cut at 16,384 characters instead of 2,048 (2.1.295).
Skills and agents. A subagent preloads at most 32 skills from its skills field, each once, but can still invoke the rest through the Skill tool (2.1.295). Agent names are limited to 256 characters, and a skill's or plugin file's name longer than that is ignored (2.1.292).
Models and context. Claude Haiku 5.5 arrived in 2.1.293. Opus 4.7 and later and the Fable models use a 1M context window by default on Bedrock, Vertex, Foundry and the Claude apps gateway, with no [1m] suffix; CLAUDE_CODE_DISABLE_1M_CONTEXT=1 keeps 200K (2.1.287). /autocompact now saves its window per model (2.1.288).
Command rename (2.1.288). claude project purge is now claude purge; the old name still works and prints a notice.

Also new in 2.1.285–2.1.286 (checked 2026-10-09)

allowedProviders (2.1.285, managed setting) limits which API providers a machine may use: the Anthropic API, a custom endpoint, Bedrock, Mantle, Vertex AI, Foundry, Claude Platform on AWS or a cloud gateway.
CLAUDE_CODE_DISABLE_WEB_FETCH (2.1.285) turns off the WebFetch tool.
Background commands can time out (2.1.285, narrowed in 2.1.289). Background Bash and PowerShell commands stop after their timeout (set with run_in_background); the default is 30 minutes and the maximum 2 hours, and Claude is told when one is stopped. Since 2.1.289 that limit applies only in unattended sessions (-p, the Agent SDK, CI and cloud); terminal, desktop app and VS Code sessions have no limit. Give long unattended jobs an explicit timeout.
Model fallback (2.1.286). When the API refuses the model your default or alias resolves to, Claude Code now retries once on the previous model of the same tier instead of failing every turn. If that fallback drops the context window from 1M to 200K tokens, the notice says so.
--bare (2.1.286) now connects only the MCP servers named on the command line, sends the model no system reminders and starts no background tasks.

New in Claude Code 2.1.277–2.1.283 (checked 2026-10-09)

AGENTS.md as project instructions (2.1.277). In a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change this under "Project instructions" in /config. Since 2.1.281 it also works on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry off.
"attribution": false (2.1.281) hides all commit and PR attribution. Older CLI versions skip a settings file that contains this form, so in files shared across versions keep the object form instead.
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH (2.1.280) changes the cap on MCP tool descriptions and server instructions, for every MCP server in the session. The default was 2,048 characters until 2.1.296, whose release notes raised it to 4,096 (check the docs for the current figure); see the MCP note above for the 16,384 cut-off on descriptions loaded through tool search.
Symlinked writes (2.1.280, a security fix). Writes through a symlinked path used to be judged by their in-tree spelling, so acceptEdits, allow rules and auto mode could approve a write that actually landed outside the project. The prompt now names where the write lands. Update if you rely on allow rules.
deniedModels and availableModelsMatch (2.1.283, managed settings). deniedModels blocks specific models even when availableModels allows them; availableModelsMatch: "exact" makes an availableModels entry allow only the exact version it names, so new model releases stay blocked until listed.
/doctor prompt-audit (2.1.283) audits your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models.
maxProseWidth (2.1.282) caps the width of Claude's prose in wide terminals; tables and code blocks keep the full width.
Bash rules with a mid-pattern :* (2.1.282, fix) were skipped in settings files while --allowedTools honoured them; they now work from every source, with a startup warning explaining how they match.

Where to find more

Claude Code's settings documentation is the authoritative list, and new keys usually appear first in its changelog. Our changelog tracks each release and what it changes.