Claude Code settings guide

Claude Code Settings and settings.json Checker

Q: Where are Claude Code settings stored?

User settings are stored in ~/.claude/settings.json. Shared project settings use .claude/settings.json, and personal project overrides use .claude/settings.local.json.

Q: Why is Claude Code ignoring my settings.json?

The usual causes are the wrong file, a higher-precedence scope, invalid JSON, an environment override, a recent update, or an IDE launch-context difference.

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

The first file stores application state. User permissions, environment values, and hooks belong in ~/.claude/settings.json.

Q: Does this tool upload my Claude Code configuration?

No. The diagnostic runs entirely in your browser and does not send pasted configuration to a server.

Find the right settings file, understand scope precedence, and diagnose configuration that does not take effect.

Check settings

Where Claude Code settings live

Choose a scope based on who should receive the setting and whether it belongs in source control.

User

`~/.claude/settings.json`

Personal settings that apply across all of your projects.

Project

`.claude/settings.json`

Shared settings committed to the repository for collaborators.

Local

`.claude/settings.local.json`

Personal overrides for one repository, normally excluded from source control.

Managed

Organization policy

Server, operating-system policy, or system-level managed settings enforced by administrators.

Local settings checker

Diagnose your active configuration

Runs in this browser tab

Choose the symptom that is closest to what you see.

01 My settings file is completely ignored Values never appear to take effect. 02 My permission rules do not work Allow, ask, or deny behaves unexpectedly. 03 It stopped working after an update The same file worked before upgrading.

Environment

Operating system

Claude Code version

Where you run Claude Code

Settings scope

Settings file path

Install state

Provider or proxy

Optional settings check

Paste only a redacted copy. Suspected secrets stop configuration analysis.

Optional settings.json Accepted placeholders: YOUR_API_KEY, ${ENV_VAR}, <redacted>.

Your configuration stays in this browser tab. Nothing is saved to local storage.

How Claude Code settings take precedence

For ordinary settings, a closer or managed source wins when the same key appears more than once.

Managed > command line > Local > Project > User

Permissions are different.

Permission rules merge across scopes. Use /status and /permissions to verify the active sources and resolved rules.

Why Claude Code settings are ignored

Start with evidence you can verify. A symptom alone does not prove a cause.

Wrong file or location

~/.claude.json is not the user settings file. User settings belong in ~/.claude/settings.json.

Scope precedence

Managed, local, project, and user settings can resolve to a different value than the file you edited.

JSON or rule shape

A syntax error can stop a file from loading. Permission rules also need supported arrays and exact tool names.

Launch environment

Proxy, base URL, and provider variables may differ between your shell and the process that opened Claude Code.

Update or startup state

A recent update is useful evidence, but verify the current version and active sources before considering a rollback.

IDE integration

VS Code and JetBrains can use a different project root, inherited environment, or interface-specific permission mode.

Verify what Claude Code actually loaded

These built-in commands are safer than changing several files at once.

/doctor: Checks installation health, settings validity, MCP configuration, and context usage.
/status: Shows active setting sources and whether managed settings are in effect.
/permissions: Shows resolved allow, ask, and deny rules with their source files.

Known issue reports need current verification

Public Claude Code issues describe permission rules appearing to be ignored in some releases and surfaces. An issue report is not proof that your installation has the same bug. Capture your version, run the built-in checks, and compare the exact behavior before changing versions.

Review permission issue #18160

Frequently asked questions

Where are Claude Code settings stored?

User settings live in ~/.claude/settings.json. Shared project settings use .claude/settings.json, and personal project overrides use .claude/settings.local.json.

Why is Claude Code ignoring my settings.json?

Usually the file did not load, a closer or managed scope overrode it, the JSON is invalid, or the launch environment differs from what you expected.

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

The first stores application state and UI preferences. User permissions, environment values, and hooks belong in the settings file inside the ~/.claude directory.

Why do my Claude Code permission rules not work?

Check the resolved rules with /permissions. Deny is evaluated before ask and allow, and a higher-precedence settings file may change the result.

Does this tool upload my Claude Code configuration?

No. The diagnostic is static browser code. It does not have an application server, account, database, or saved report.

Local by construction

Your configuration stays in this browser tab.

The tool checks pasted text with browser JavaScript, does not use browser storage, and blocks common secret patterns before parsing. You should still replace every real credential with a placeholder.

Official sources

Sources last reviewed July 12, 2026.