Claude Code settings.json, explained and tested

Claude Code writes two of these files for you. ~/.claude/settings.json appears the first time you change a /config option it stores there, such as the theme. .claude/settings.local.json appears the first time you pick "Yes, and don't ask again" on a permission prompt, and in a git repository Claude Code adds it to your global git excludes so it never lands in a commit.

It reads the shared .claude/settings.json from the folder you start in, so start Claude Code at the repository root to use a file committed there. The local file lives at the repository root even when you start in a subfolder.

To try a value for one session without saving it, pass it at start: claude --settings '{"model": "opus"}'. It sits above every file except managed settings and is gone when the session ends.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git push *)",
      "Bash(docker compose up *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)"
    ]
  }
}

Lists merge, and deny beats allow across files

Each file can add permissions.allow entries without removing another file's. That merge cuts both ways: a deny rule in your user file blocks an allow rule in the project file, and the reverse. A few model keys follow their own rules: fallbackModel takes its whole value from one file, modelPicker is read only from managed, --settings and user files, and a managed availableModels list replaces the lists in other files.

Keys where the stricter value wins

For a few security keys, Claude Code honors a restrictive value from a lower file even over managed settings:

Does it match? The documented wildcard examples

Type a command and every rule from the docs' wildcard table says whether it matches. Click an example to load it.

Compound commands and wrappers

Claude Code splits commands on &&, ||, ;, |, |&, & and newlines. An allow rule must match every part; a deny or ask rule fires on any part, including commands inside $( ). Before matching it strips timeout, time, nice, nohup, stdbuf, command, builtin, noglob and bare xargs, so Bash(npm test *) also covers timeout 30 npm test. Runners such as npx, devbox run and docker exec are not stripped, so Bash(devbox run *) also matches devbox run rm -rf ..

What a Bash rule does not stop

A Bash rule matches the command text Claude writes. The same program called another way slips past it:

Where a path rule points

Read and Edit rules use gitignore patterns with four anchors. A single leading slash is the trap: it anchors at the project root in a project file and at ~/.claude in your user file, never at the filesystem root.

1. Allow what you approve every day. Bash(npm run test *) and Bash(npm run lint) remove most prompts on their own.
2. Never allow an interpreter or an encoder. Bash(python *) runs any script, and Bash(base64 *) prints any file.
3. Turn on the sandbox. With sandbox.enabled and the default autoAllowBashIfSandboxed, sandboxed Bash runs without asking, inside OS-level limits. Deny rules still apply.
4. Audit the local file. Every "Yes, and don't ask again" adds an allow rule to .claude/settings.local.json.

No key matches. Clear the search or pick All.

• Run /status. The Setting sources line lists every file Claude Code loaded. A file missing from it was not read.
• Run claude doctor. It lists entries Claude Code rejected and why.
• Check the higher levels. A key in managed, --settings, local or project settings beats the same key in your user file.
• Check the file can set that key. Managed-only keys do nothing elsewhere, and global config keys live in ~/.claude.json. The doctor flags both.
• Accept workspace trust. Project allow rules, additionalDirectories, marketplaces and most env values wait for it. claude -p shows no dialog, so in a folder you never trusted it skips project allow rules.
• Fix the JSON. A Settings Error means the whole file was skipped. A Settings Warning means only some entries were.
• Restart for start-only keys. model is read at start. Use /model mid-session.
• Look for ANTHROPIC_MODEL. An exported ANTHROPIC_MODEL beats the model key in every file, managed included.
• Audit settings.local.json. Every "Yes, and don't ask again" adds an allow rule there, and old ones can outlive the reason you added them.

One more place: the env block in settings points Claude Code at a different endpoint with ANTHROPIC_BASE_URL. If you plan to run a model on your own machine, check what your hardware can run first.