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

Start with the user file for settings you want everywhere. Use a project file only when the configuration belongs to one repository.

Quick answer by operating system

Find your Claude Code settings.json file

macOS and Linux ~/.claude/settings.json

The tilde expands to your home directory.

Windows %USERPROFILE%\.claude\settings.json

This is the Windows equivalent of ~/.claude/settings.json.

Inside a project .claude/settings.json

Use .claude/settings.local.json for personal, uncommitted overrides.

If you set CLAUDE_CONFIG_DIR, Claude Code uses that directory instead of ~/.claude for user configuration.

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

Run these checks before editing several files or assuming that an update caused the problem.

/status: Which settings files did Claude Code load? Check the Setting sources line for user, project, local, or managed settings.
/doctor: Is the configuration valid? Look for invalid JSON, unsupported keys, schema errors, and installation problems.
/permissions: Which permission rule is actually in effect? Review the resolved allow, ask, and deny rules and the settings file each rule came from.

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 20, 2026.