Skip to main content

settings.json: The Config System

Intermediate

settings.json is where Claude Code's configuration lives — permissions, hooks, environment variables, model defaults, and more. Understanding the tiers is the key.

What you'll learn
  • The five-level precedence stack, and which file wins when two of them set the same key
  • Why environment variables are not a tier, and what that means for ANTHROPIC_MODEL
  • Which file to put a setting in: committed team convention, personal override, or one-session experiment
  • The four sections you will actually edit, and where each one is documented in depth
  • How to edit without breaking the file, and what never belongs in a committed settings file

The tiers (highest precedence first)​

When the same key is set in more than one place, Claude Code uses the value from the highest level that sets it:

Guided walkthrough1 of 5
  1. managed-settings.json, an MDM policy, or server-managed settings from the claude.ai console. Nothing you set overrides them (bar a few security-sensitive exceptions).
Environment variables are not a tier

They sit outside this stack and are resolved per key. For example ANTHROPIC_MODEL applies over the model key from any file, while ANTHROPIC_DEFAULT_MODEL applies only when no file sets model.

Commit the shared file, ignore the local one

Put team conventions in .claude/settings.json (committed). Put personal tweaks and machine-specific paths in .claude/settings.local.json (git-ignored). This keeps the team consistent without forcing your preferences on others.

What you'll commonly set​

  • permissions — allow/ask/deny rules. See Permissions.
  • hooks — commands that run at lifecycle events. See Hooks.
  • env — environment variables for the session.
  • Model / behaviour defaults — e.g. preferred model.

Editing safely​

  • Keep it valid JSON (a trailing comma will break it).
  • Prefer narrow permission rules over broad ones.
  • Never put secrets in a committed file — use env references or a secrets manager.

Try a setting for one session without writing it to any file

claude --settings '{"permissions":{"allow":["Bash(git log *)"]}}'

Ready-to-copy starting files live in Hooks & settings.json Recipes. When a file is malformed or a key isn't doing what you expect, claude doctor prints settings-file validation errors without starting a session — see the CLI page for that and --safe-mode.

Check yourself​

Check yourself

0/3
  1. Your repo's committed .claude/settings.json sets a model, and your ~/.claude/settings.json sets a different one. Which applies?
  2. Where should a machine-specific absolute path go?
  3. Which statement about environment variables is correct?
Key takeaways
  • Five tiers, one rule: the highest level that sets a key wins. Managed is absolute; user settings are the weakest.
  • Committed file for team conventions, local file for personal and machine-specific values, --settings for a throwaway experiment.
  • Environment variables are not a tier. Check each variable's own rule rather than assuming a position in the stack.
  • Secrets never go in a committed settings file.
  • When a setting seems ignored, run claude doctor for validation errors before changing anything else.

Next​