Settings & Scopes: settings.json Explained

One schema, several files

Claude Code behavior (permissions, hooks, default model, environment variables and more) is configured in settings.json files at different scopes:

Precedence: who wins?

When the same setting appears in more than one place, the more specific and more authoritative scope wins:

1. Managed settings (highest, can't be overridden)
2. Command-line flags for this session
3. Local project settings
4. Project settings
5. User settings (lowest)

Some keys merge instead of replacing. Permission rules from different scopes are combined, and hooks from every scope all run. A deny rule anywhere still denies.

A realistic project settings file

{
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(pnpm lint *)", "Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }]
      }
    ]
  }
}

This one file pre-approves safe test and lint commands, makes pushes ask first, blocks reading secrets and auto-formats every edit, for everyone on the team.

Handy keys to know

Inspect before you guess

• /config opens the settings UI.
• /status shows your current setup: account, model, and which settings sources loaded.
• /permissions lists every active rule and where it came from.

Check your understanding