Claude settings.json: Claude Code Config Reference

Claude settings.json reference: where each Claude Code config file lives, which one wins, the key settings and environment variables, plus an example.

Josh Pocock8 min read

settings.json cover

AI Coding

settings.json

Stride AI Academy

Claude settings.json is the JSON file where you configure Claude Code: the model it starts with, environment variables, hooks, the status line and permission rules. There are four of them. ~/.claude/settings.json applies to you everywhere, .claude/settings.json to everyone in a project, .claude/settings.local.json to you in one project, and managed settings to your whole organization. When the same key is set twice, the higher level wins.

This guide is a reference for Claude Code config: where each file lives, the precedence order, the keys worth knowing, the env block and common environment variables, what ~/.claude.json is for, a copyable example, and how to check what applies. Everything here was checked against Claude Code's settings docs, the settings reference, the environment variables reference and the managed settings docs on November 20, 2026.

Where each settings file lives

Scope File Who it affects
User ~/.claude/settings.json You, in every project on this machine
Shared project .claude/settings.json Everyone in the project, once committed to Git
Project local .claude/settings.local.json You, in this one project
Managed managed-settings.json and other managed sources Everyone your organization deploys it to

On Windows, ~/.claude means %USERPROFILE%\.claude. A bare .claude means the folder inside your project.

Installing Claude Code doesn't create any of these files. It writes .claude/settings.local.json when you choose "Yes, and don't ask again" on a permission prompt, and keeps it out of Git for you. If you create the local file by hand, add it to .gitignore yourself.

The file-based managed settings live in a system directory:

  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux and WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\Program Files\ClaudeCode\managed-settings.json

Organizations can also deliver managed settings through MDM or from the claude.ai admin console.

Which settings file wins

From highest to lowest:

  1. Managed settings. Nothing in your own files overrides a managed key.
  2. Command line. JSON passed with --settings, for that session only.
  3. Project local. .claude/settings.local.json
  4. Shared project. .claude/settings.json
  5. User. ~/.claude/settings.json

So if your team's file sets a model and you want a different one, put your model in .claude/settings.local.json. Only your sessions change.

Two rules catch people out. First, lists merge instead of overriding. If permissions.allow is set in three files, Claude Code combines all three lists. Second, environment variables aren't a level in this stack. Whether a shell variable or a settings key wins is decided pair by pair. For example, ANTHROPIC_MODEL exported in your shell applies over the model key from any file.

To try a value for one session without saving it:

Terminal
claude --settings '{"model": "claude-opus-5-5"}'

Settings keys worth knowing

The settings reference lists every key. These are good ones to start with.

Key What it does
model The model every new session starts with. You can still switch with /model
effortLevel Default effort level: low, medium, high or xhigh
env Environment variables for every session and its subprocesses
hooks Your own commands at points in Claude Code's lifecycle
statusLine A command that renders a status line below the prompt
permissions Allow, ask and deny rules, plus the default permission mode
attribution Change or hide the commit trailer and pull request text
cleanupPeriodDays Days to keep session transcripts. Default 30, minimum 1
outputStyle An output style by name, such as "Explanatory"
language Have Claude reply in another language by default
alwaysThinkingEnabled Set to false to turn extended thinking off
ultracode Start sessions with ultracode workflows on

A few notes on the ones that need more than a line.

hooks. Each event maps to a list of matcher groups, and hooks merge across files instead of replacing each other. Our Claude Code hooks tutorial covers events and examples.

statusLine. It takes "type": "command" and a command string, with optional padding and refreshInterval. See our Claude Code statusline guide for ready-made scripts.

attribution. This replaced includeCoAuthoredBy, which is deprecated since v2.0.62. Set "attribution": false to hide all attribution (Claude Code v2.1.281 or later), or set commit and pr strings to change the text.

cleanupPeriodDays. Setting 0 fails validation. For long retention, pick a large number such as 3650.

Permissions, in short

The permissions key holds allow, ask and deny lists and a defaultMode. Deny rules block an action, ask rules prompt, and allow rules skip the prompt. One scope rule matters here: defaultMode values auto and bypassPermissions don't take effect from project or local settings, so set them in ~/.claude/settings.json.

For the full rule syntax and examples, read our guide to Claude Code permissions.

The env block and useful environment variables

Put environment variables under env and Claude Code applies them to every session, however claude was launched:

JSON
{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "DISABLE_AUTO_COMPACT": "1"
  }
}

Things to know about env:

  • A value here overwrites the same variable exported in your shell, in most sessions.
  • Values are copied as written. No shell expands ~ or $HOME, so write absolute paths.
  • Values are plain text and reach every subprocess. For API credentials, use apiKeyHelper instead.
  • To cancel a shell export you can't unset, set it to "".
  • Project and local settings can't set some variables, such as CLAUDE_CONFIG_DIR. Set those in your shell or user settings.

The environment variables reference lists them all. These are the ones that come up most:

Variable What it does
ANTHROPIC_API_KEY Uses an API key instead of your subscription, even when logged in
ANTHROPIC_MODEL Sets the model. --model and /model override it
ANTHROPIC_BASE_URL Routes requests through a proxy or gateway
CLAUDE_CODE_EFFORT_LEVEL Sets effort. Overrides --effort, /effort and the effortLevel setting
CLAUDE_CONFIG_DIR Moves the config folder from ~/.claude, handy for a second account
BASH_DEFAULT_TIMEOUT_MS Default timeout for shell commands. Default 120000 (2 minutes)
BASH_MAX_TIMEOUT_MS Longest timeout Claude can set. Default 600000 (10 minutes)
MCP_TIMEOUT MCP server startup timeout. Default 30000 (30 seconds)
DISABLE_AUTO_COMPACT Set to 1 to stop automatic compaction. /compact still works
DISABLE_AUTOUPDATER Set to 1 to stop background updates. claude update still works
DISABLE_TELEMETRY Opts out of telemetry. Even 0 opts out, so unset it to turn it back on
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC Turns off auto-updates, telemetry, error reporting and other nonessential traffic

One trap: if ANTHROPIC_API_KEY is set in your shell, Claude Code bills that key instead of your Pro, Max or Ultra plan. In interactive mode you're asked to approve it once, but in -p mode it's used straight away. See how much Claude Code costs for how plans and API billing differ.

~/.claude.json vs settings.json

They look similar but do different jobs. ~/.claude/settings.json is your settings file, the one you edit. ~/.claude.json is a file Claude Code writes for itself, and you don't need to edit it. It holds:

  • Your account details
  • Personal MCP server configurations
  • Per-project state, such as trust decisions
  • A short list of global config keys that /config writes, such as autoConnectIde and diffTool

Those global config keys only apply from ~/.claude.json, not from any settings file. Standing instructions for Claude belong in neither file. Use CLAUDE.md for those.

A copyable example

This user settings file sets a default model, adds environment variables, a status line, a hook and a few permission rules. It's strict JSON, so no comments or trailing commas.

JSON
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "cleanupPeriodDays": 60,
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/check-bash.sh" }
        ]
      }
    ]
  },
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

The $schema line gives you autocomplete and validation in editors that support JSON schema. It can lag behind new releases, so a warning on a new key doesn't always mean it's wrong. Swap the script paths for your own.

How to check what applies

  • /status shows a Setting sources line listing every settings file loaded for the session, and names the managed source if there is one.
  • /config opens a menu of personal options and saves your changes for you. It's not a view of your full settings.json. To set one option directly, use /config key=value, such as /config verbose=true.
  • /permissions lists your permission rules and which file each came from.
  • claude doctor lists entries Claude Code rejected.

Claude Code reloads most edits without a restart, including permissions and hooks. A few keys, such as model and effortLevel, are read only at session start, so use /model or /effort to change them mid-session. If a file has broken JSON, Claude Code shows a Settings Error at the next start and lets you fix it, exit or continue without it.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.

FAQ

Where is the Claude Code settings.json file?

Your personal file is ~/.claude/settings.json, which is %USERPROFILE%\.claude\settings.json on Windows. Project files are .claude/settings.json (shared) and .claude/settings.local.json (just you) inside the project folder.

Which Claude Code settings file takes precedence?

Managed settings win, then --settings on the command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. Lists such as permissions.allow merge across files instead of replacing each other.

How do I set environment variables in Claude Code?

Add them under the env key in a settings file, such as "env": {"DISABLE_AUTO_COMPACT": "1"}, or export them in your shell before running claude. A settings file value overwrites the shell value in most sessions.

What is the difference between ~/.claude.json and settings.json?

~/.claude/settings.json is the settings file you edit. ~/.claude.json is written by Claude Code and holds account details, personal MCP servers, project trust state and a few global config keys that /config manages.

Does Claude Code still support includeCoAuthoredBy?

It still reads it, but it's deprecated since v2.0.62. Use the attribution key instead, which lets you change or hide the commit trailer, the pull request text and the session link separately.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides