Settings Check

Practical settings.json reference

Claude Code settings.json Guide

Choose the right file, start from a safe example, and verify which setting actually wins.

See starter file Run settings checker

The short answer

Most people need the user file. Move to a project scope only when the setting belongs to that repository.

Personal defaults on macOS and Linux
~/.claude/settings.json
Personal defaults on Windows
%USERPROFILE%\.claude\settings.json
Settings the team should share
<project>/.claude/settings.json
Private overrides for one project
<project>/.claude/settings.local.json

If CLAUDE_CONFIG_DIR is set, Claude Code uses that directory in place of ~/.claude for user configuration.

Safe starter settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Start small, then add one behavior at a time

The schema line enables editor autocomplete and inline validation. The permission example approves one narrow test command and denies common secret locations.

Adjust every rule to match your repository. A broad allow rule can remove useful approval prompts, while a broad deny rule can block normal work.

Write permission rules that stay narrow

An allow rule removes a prompt for a matching action. It does not turn the full tool list into an allowlist. Review every pattern against a real command before sharing it.

Prefer an exact command first
Bash(npm run lint) is easier to review than a rule that approves every npm command. Expand a rule only after you can name the extra commands it needs to match.
Use trailing wildcards deliberately
Bash(npm run test *) matches the command prefix plus following arguments. The space before * creates a word boundary. Without that space, a pattern can match a longer command name you did not intend.
Keep sensitive paths in deny
A deny rule blocks the action even when another scope contains a broader allow rule. Cover each real secret location your repository uses, then verify the result with /permissions.
Use ask for consequential actions
An ask rule keeps an explicit approval point for a matching action. Rules are checked in the order deny, ask, allow, and the first match wins.

Choose scope intentionally

A correct value in the wrong scope still produces confusing behavior.

User

~/.claude/settings.json

Use this for personal permissions, environment defaults, hooks, and preferences that should follow you across projects.

Shared project

Commit .claude/settings.json when every collaborator should receive the same project behavior.

Personal project

Use .claude/settings.local.json for machine-specific paths, experiments, or personal overrides. In a Git worktree, current Claude Code resolves this file to the main checkout root.

Managed

Organization policy can arrive from server delivery, operating-system policy, or a system-level managed settings file. It cannot be overridden by user or project settings.

Decide what the repository should carry

Shared settings are part of the project's operating policy. Review them with the same care as build scripts and automation.

Commit team behavior

Use .claude/settings.json for rules, hooks, and supported settings that every collaborator should receive. Keep the file readable, explain non-obvious rules in the pull request, and avoid broad approvals that are hard to audit.

Keep personal values local

Use .claude/settings.local.json for personal experiments, machine paths, or one-project overrides. When Claude Code creates it in a Git repository, it adds the path to Git's global excludes. If you create it by hand, add it to .gitignore yourself, then confirm repository status before committing.

Put each kind of configuration in the right file

Claude Code uses several configuration files. Their jobs overlap less than their names suggest.

settings.json
Permissions, environment values, hooks, plugins, and supported tool behavior.
~/.claude.json
Sign-in state, MCP configuration, per-project state such as trust decisions, global config keys, and caches.
CLAUDE.md
Project instructions and context for Claude. It guides behavior but does not enforce permission boundaries.
.mcp.json
Project-scoped MCP server definitions that a team can share with the repository.

Know which value wins

For scalar values, higher-priority sources override lower-priority ones.

Managed > command line > Local > Project > User

Verify the loaded configuration

Do not edit several files at once. Use one observation to decide the next change.

  1. Parse the JSON

    Settings files are strict JSON, so remove comments and trailing commas. Run claude doctor for read-only details about rejected settings, or /doctor for the interactive checkup.

  2. Locate the active sources

    Run /status and read the Setting sources line. It confirms which files loaded, but it does not identify the source of every individual key.

  3. Resolve permission rules

    Run /permissions to see the current allow, ask, and deny rules plus the settings file each rule came from.

  4. Test one narrow behavior

    Change one value, reproduce one action, and record the result. This separates a scope problem from a rule-pattern problem.

  5. Confirm the launch context

    The CLI, VS Code, and JetBrains use the same scope system, but a different working directory, inherited environment, or project root can change what loads. Reproduce the issue from the same interface where you first saw it.

  6. Separate settings from instructions

    Put permissions and tool behavior in settings.json. Put project conventions and working guidance in CLAUDE.md. A well-written instruction can influence what Claude tries, but it cannot replace an enforced permission rule.

Some settings have scope restrictions. For example, permissions.defaultMode values auto and bypassPermissions do not take effect from shared project or local settings; some telemetry variables in env also ignore those scopes.

The published JSON schema is useful but can lag a newly documented field. Treat a warning on a recent official field as a reason to recheck the current documentation, not automatic proof that the field is invalid.

Local diagnostic

Still not taking effect?

Run the browser-only checker to rank likely causes from your path, scope, version, launch surface, and redacted JSON.

Run settings checker

settings.json questions

Where is Claude Code settings.json 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.

Should I commit .claude/settings.json?

Commit it only when the settings are intended for the whole team. Keep machine-specific or personal project values in .claude/settings.local.json.

Why does my settings.json appear to be ignored?

The file may be in the wrong location, contain invalid JSON, lose to a higher-precedence scope, or be affected by a command-line or environment override. Use /status, /doctor, and /permissions to inspect the active configuration.

Is ~/.claude.json the same as ~/.claude/settings.json?

No. ~/.claude/settings.json stores settings such as permissions, environment values, and hooks. ~/.claude.json stores application state and other global configuration.

Official Claude Code sources

Sources last reviewed September 27, 2026.