Claude Code Settings

Claude Code's settings live in JSON files at four levels: ~/.claude/settings.json for you on every project, .claude/settings.json committed for a whole repository, .claude/settings.local.json for you in one repository, and managed settings set by an organization, which override everything; in a session, /config opens the settings screen (Settings files and precedence, read Nov 6, 2026). The reference documented 248 keys and the environment variables page about 400 variables on Nov 6, 2026, but a handful cover what most people change.

Quick facts

Sources for the table: Settings files and precedence, Commands and Environment variables, Anthropic, read Nov 6, 2026.

Which settings file wins?

3:41 From highest to lowest: managed settings, then --settings <file-or-json> on the command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. Managed settings are the only kind a user cannot override, which is why security teams put policy there (Settings files and precedence, read Nov 6, 2026). Some keys merge instead of replacing: hooks from every level all run, and permission rules from every file combine.

There is a fifth file, ~/.claude.json, which Claude Code writes for itself: account details, MCP servers you added at local or user scope, and per-project state. It is not meant for hand editing the way settings.json is.

How do you change settings?

1. Type /config in a session for the settings screen, or /config key=value to set one key directly (this also works in claude -p runs).
2. Ask Claude: /update-config (or a plain request such as "allow npm test without asking") has Claude edit the right file for you.
3. Edit the JSON yourself. A minimal user file might be:

{
  "model": "opus",
  "effortLevel": "high",
  "permissions": { "deny": ["Read(./.env)"] },
  "env": { "DISABLE_AUTOUPDATER": "1" }
}

Sources: Commands and Advanced setup, read Nov 6, 2026. The env key sets environment variables for every session, so you need not export them in your shell.

Common settings

The reference groups its keys roughly like this (Settings reference, read Nov 6, 2026):

• Model: model, availableModels (an admin's allowlist), effortLevel, fallbackModel, fastMode, outputStyle, ultracode.
• Permissions: permissions.allow, ask and deny, defaultMode, additionalDirectories, disableBypassPermissionsMode, autoMode, disableAutoMode (see Claude Code Permissions and Modes).
• Sandbox: sandbox.enabled, sandbox.filesystem.allowWrite, sandbox.network.allowedDomains, sandbox.excludedCommands.
• Context and memory: autoCompactWindow, autoMemoryEnabled, claudeMdExcludes, cleanupPeriodDays (how long local transcripts are kept, 30 days by default).
• Interface: theme, editorMode, statusLine, spinnerVerbs, viewMode, voice.
• Git attribution: attribution.commit, attribution.pr, includeCoAuthoredBy, which control the lines Claude adds to commits and pull requests.
• Plugins and MCP: enabledPlugins, extraKnownMarketplaces, strictKnownMarketplaces, allowedMcpServers.

Models and effort

1:27 The default model on Pro, Max, Ultra, Team, Enterprise and the API is Claude Opus 5.5, at medium effort (Model configuration, read Nov 6, 2026). Aliases are default, best, fable, opus, sonnet, haiku, the [1m] variants and opusplan (Opus while planning, Sonnet while doing). Change the model with /model, claude --model, ANTHROPIC_MODEL or "model" in settings, in that order of priority. Effort levels run low, medium, high, xhigh and max; set them with /effort, --effort, effortLevel or CLAUDE_CODE_EFFORT_LEVEL, and type ultrathink in a prompt for one deeper turn. Anthropic notes that max can overthink ordinary tasks. Fable is never the default and may bill to usage credits. More on Extended and Adaptive Thinking.

Environment variables worth knowing

From the environment variables page (read Nov 6, 2026): ANTHROPIC_API_KEY (API billing instead of a subscription once approved), ANTHROPIC_BASE_URL (a proxy or gateway), CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX and CLAUDE_CODE_USE_FOUNDRY for cloud providers, BASH_DEFAULT_TIMEOUT_MS (default 120000, two minutes) and BASH_MAX_TIMEOUT_MS (default 600000, ten minutes), MAX_THINKING_TOKENS, HTTPS_PROXY, DISABLE_AUTOUPDATER, and the privacy switches DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. One quirk is documented: setting the telemetry or error-reporting variable to 0 or false still opts out.

Status line

The status line is a bar at the bottom of Claude Code that runs any script you choose; the script receives session data as JSON (model, context use, cost, git branch) and prints what to show. The quickest way to make one is to describe it: /statusline show model name and context percentage with a progress bar, and Claude writes the script into ~/.claude/ and wires up settings. By hand it is "statusLine": {"type": "command", "command": "~/.claude/statusline.sh", "padding": 2}. A custom status line hides most footer hints such as "esc to interrupt" (Customize your status line, read Nov 6, 2026).

Output styles

An output style is a set of instructions that changes Claude's role, tone and format for a whole session. Besides Default there are four built in: Proactive (starts at once and makes reasonable assumptions), Concise (results first, no recaps; added Aug 17 to 21, 2026), Explanatory (adds "Insight" notes about its choices) and Learning (explains and leaves small pieces for you to write). Switch with /output-style or "outputStyle"; custom styles are Markdown files in ~/.claude/output-styles or .claude/output-styles/ (Output styles, read Nov 6, 2026). A style is guidance, not a guarantee; Anthropic points to hooks for anything that must always happen.

The .claude folder

Besides settings, a project's .claude/ folder and your ~/.claude/ hold CLAUDE.md, agents/ for subagents, skills/ and commands/ for skills, rules/ for path-scoped instructions, hook scripts and workflows (Explore the .claude directory, read Nov 6, 2026). Local transcripts sit in plain text under ~/.claude/projects/.

Frequently asked questions

Where is the Claude Code settings.json file? Your personal file is ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json). A project's shared file is .claude/settings.json in the repository, and personal project overrides go in .claude/settings.local.json.

Which Claude Code settings file takes priority? Managed settings first, then --settings on the command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json.

How do I change the default model in Claude Code? Set "model" in a settings file, for example "model": "sonnet", or use /model in a session or claude --model at start. Opus 5.5 is the default on paid plans and the API.

Can I turn off telemetry in Claude Code? Yes. Set DISABLE_TELEMETRY, DISABLE_ERROR_REPORTING or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC in your environment or in the env key of settings.

How do I make a custom status line in Claude Code? Type /statusline followed by what you want to see, and Claude writes the script and updates settings. You can also point "statusLine" at your own script, which receives session data as JSON.

Sources

• Settings files and precedence, Anthropic, read Nov 6, 2026
• Settings reference, Anthropic, read Nov 6, 2026
• Environment variables, Anthropic, read Nov 6, 2026
• Model configuration, Anthropic, read Nov 6, 2026
• Customize your status line, Anthropic, read Nov 6, 2026
• Output styles, Anthropic, read Nov 6, 2026
• Explore the .claude directory, Anthropic, read Nov 6, 2026
• Commands, Anthropic, read Nov 6, 2026
• Advanced setup, Anthropic, read Nov 6, 2026
• How auto mode works with Claude Code, Claude, Aug 4, 2026 (video)
• Using Claude Opus 5.5 as your daily driver, Claude, Sep 23, 2026 (video)