Claude Code settings.json: file locations, precedence, and key settings

• User: ~/.claude/settings.json applies to you in every project on this machine. Use it for personal preferences such as theme, default model, and your own permission rules.
• Shared project: .claude/settings.json applies to everyone working in the folder. Commit it so teammates get the same permissions, hooks, plugins, and environment variables.
• Project local: .claude/settings.local.json applies to you in one project only. Claude Code adds it to your global git excludes the first time it writes the file; if you create it by hand, add it to .gitignore yourself.
• Managed: managed-settings.json, MDM policies, or server-managed settings from the claude.ai console apply to everyone your organization deploys them to, and nothing you set overrides them apart from a few security-sensitive exceptions.

File-based managed settings live at /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, and C:\Program Files\ClaudeCode\managed-settings.json on Windows. On Windows, ~/.claude means %USERPROFILE%\.claude. Installing Claude Code does not create any settings file.

When the same key appears in more than one place, Claude Code uses the value from the highest level that sets it. The order, highest first:

• Managed settings
• Command line arguments, such as claude --settings or --model, for one session
• Project local settings (.claude/settings.local.json)
• Shared project settings (.claude/settings.json)
• User settings (~/.claude/settings.json)

List keys such as permissions.allow merge across files instead of overriding each other, so each file can add entries. Environment variables are not a level in this stack; for example, ANTHROPIC_MODEL exported in your shell applies over the model key from any file. Run /status to see the Setting sources line listing which files loaded.

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

• $schema: point it at https://json.schemastore.org/claude-code-settings.json for autocomplete and validation in editors that support JSON schema. The schema can lag behind the newest releases.
• permissions: allow, ask, and deny arrays of rules such as Bash(npm run *) or Read(./.env), plus defaultMode for the permission mode a session starts in. Allow rules from a project file apply only after you trust the folder; deny and ask rules apply right away.
• env: environment variables for every session and the subprocesses Claude Code starts.
• model: the model every new session starts with. You can still switch mid-session with /model.
• hooks: commands, prompts, agents, HTTP requests, or MCP tools that run at lifecycle events such as PreToolUse. Hooks merge across files.
• statusLine: runs your own command to render a status line below the prompt.
• enabledPlugins and extraKnownMarketplaces: turn plugins on or off and register plugin marketplaces.

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

Settings files are strict JSON: a comment or trailing comma is a syntax error that Claude Code reports as a Settings Error at the next start.

Run /config inside Claude Code and open the Config tab to change a short set of personal options such as theme, editor mode, and verbose output. It does not list every settings key. Most options save to ~/.claude/settings.json, a few such as Show tips save to .claude/settings.local.json, and global config options save to ~/.claude.json.

/config verbose=true

Claude Code watches settings files and applies most edits, including permissions and hooks, to the running session without a restart. A few keys, such as model, are read only at session start. /config is part of the terminal interface; the VS Code chat panel and the desktop app do not open it.