Claude Code Settings: The settings.json Guide.

Claude Code settings live in settings.json files, and there are four of them at different levels: user, project, local, and managed. They stack, with the more specific file overriding the more general one, so a project setting beats your personal default and a managed setting beats everything. Knowing which file wins is most of what makes Claude Code configuration click.

I'm Tom, and I run a fairly opinionated settings.json: model pinned, reasoning effort turned up, session history kept far longer than the default, hooks wired in, and a hard deny rule on reading any .env file. This post covers where the files live, the precedence order, and the handful of keys worth setting on day one.

[CTA-BLUEPRINT]

What is the Claude Code settings.json file?.

The settings.json file is where Claude Code reads its configuration: which model to use, what tools it may run, environment variables, hooks, and more. It is plain JSON, and the same keys work in every one of the four settings files. The difference between those files is scope and who they apply to, not syntax.

A tip that saves real time: add "$schema": "https://json.schemastore.org/claude-code-settings.json" to the top of your file. Your editor then gives you autocomplete and inline validation for every available setting, so you stop guessing at key names.

The Claude Code settings hierarchy.

Claude Code reads four settings files, each with a different scope. Understanding the four is the foundation, because a setting that "won't take" is almost always being overridden by a more specific file.

• ✓User (~/.claude/settings.json): your personal preferences across every project. Not shared.
• ✓Project (.claude/settings.json): team settings committed to the repo, so everyone working in it inherits them.
• ✓Local (.claude/settings.local.json): your personal overrides for one project, gitignored so they stay off the team.
• ✓Managed: deployed by an organization's IT for fleet-wide security and compliance, and it cannot be overridden.

What is the Claude Code settings precedence order?.

When the same key is set in more than one file, Claude Code applies them in a fixed order from highest priority to lowest: managed settings, then command-line arguments, then local, then project, then user. So a managed policy wins outright, a --model flag beats your files for that session, and your gitignored local file overrides the shared project file, which in turn overrides your global user defaults.

The practical rule that follows: put personal defaults in your user file, team agreements in the project file, and your own per-project tweaks in the local file. When a setting is not behaving, check whether a higher-priority file is setting the same key. That one habit resolves most configuration confusion.

The Claude Code settings that matter.

You do not need to set most keys. A handful do real work, and these are the ones I actually touch. For the deeper subsystems, each has its own guide.

• ✓`model`: the default model for Claude Code, overridable per session with --model. Read once at startup, so it applies on the next restart.
• ✓`permissions`: allow, deny, and ask rules for tool execution. I keep a hard deny on reading any .env file so secrets never reach the model. This is the security-critical one. For the risky end of permissions, see Claude Code dangerously skip permissions.
• ✓`hooks`: custom commands that fire at lifecycle events, which is how you automate around the agent. Full detail in my Claude Code hooks guide.
• ✓`env`: environment variables applied to every session, useful for things like DISABLE_AUTOUPDATER or a git bash path on Windows.
• ✓`cleanupPeriodDays`: how long session files are kept before deletion. The default is 30. I set mine far higher because I lean on session history and the Claude Code memory it feeds.
• ✓`statusLine`: points at a script for a custom status bar. See my Claude Code status line guide.
• ✓`outputStyle` and `attribution`: adjust the response style and customize git commit and PR bylines respectively.

Here is a compact example that sets several of those at once, close to the shape of my own user file:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-8",
  "permissions": {
    "deny": ["Read(**/.env)", "Read(**/.env.*)"]
  },
  "env": {
    "DISABLE_AUTOUPDATER": "0"
  },
  "cleanupPeriodDays": 90,
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}

Most settings reload automatically when you change them, including permissions and hooks. A couple, including model and outputStyle, are read once at startup and apply on the next restart. You can edit the file directly or use the /config command for an interactive interface, including /config verbose=true to change a single option without opening the UI.

[CTA-BLUEPRINT]

Claude Code settings FAQ.

Where is the Claude Code settings.json file?

There are four. Your personal user settings live at ~/.claude/settings.json. Project settings shared with your team live at .claude/settings.json in the repo. Your gitignored personal overrides for a project live at .claude/settings.local.json. Managed settings are deployed by IT at a system path and cannot be overridden.

What is the precedence order of Claude Code settings?

From highest to lowest priority: managed settings, command-line arguments, local settings, project settings, then user settings. A managed policy wins outright, a command-line flag beats your files for that session, and a more specific file overrides a more general one when they set the same key.

What is the difference between project and local settings?

Project settings (.claude/settings.json) are committed to the repo and shared with your whole team. Local settings (.claude/settings.local.json) are gitignored and apply only to you in that project. Use project settings for team agreements and local settings for your own per-project tweaks that should not be shared.

How do I change the model in Claude Code settings?

Set the model key in your settings.json to the model you want as the default. You can override it for a single session with the --model flag, which takes precedence. The model setting is read once at startup, so a change applies the next time you start Claude Code.

How do I stop Claude Code from reading sensitive files?

Add a permissions block with a deny rule for the file path, such as denying Read on any .env file. A matching deny rule keeps both the file's contents and, with the IDE integration, the open-file notice from reaching Claude. This is the cleanest way to keep secrets out of the model's context.

Do Claude Code settings reload without restarting?

Most do. Settings like permissions, hooks, and apiKeyHelper reload automatically when changed. A few are read once at startup and apply on the next restart, including model and outputStyle. Run claude doctor if you want to validate that your settings file is being read correctly.

Sources and citations.

• ✓Claude Code settings — official file hierarchy, precedence order, and the full list of available settings.
• ✓Claude Code hooks — the hooks setting and the lifecycle events it fires on.
• ✓Claude Code permissions — the allow, deny, and ask rules and managed-settings enforcement.

Ready to make Claude Code work the way you do?.

Dialing in your settings is the groundwork. The payoff is what you build on top of it. My free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. Start there.