Claude Code settings.json: The Complete 2026 Field Reference

.claude/settings.json is not a small file anymore. Claude Code has shipped enough settings — sandboxing, auto mode, hooks, remote control, managed policy — that no one keeps the full field list in their head. Most guides cover the five or six keys people actually set by hand (model, permissions, env, hooks) and stop there.

This is the field list itself: every documented key, grouped by what it actually controls, plus the precedence order that decides which file wins when two of them disagree.

If you’re trying to understand where a specific setting came from — or why one teammate’s Claude Code behaves differently from another’s — start with the precedence table below, not the field list.

Where settings.json lives

Claude Code reads configuration from five sources, checked in this order (highest priority first):

One exception matters more than the rest of the table: permissions.allow, permissions.deny, and permissions.ask don’t override across scopes — they merge. A deny rule in managed settings and an allow rule in your local settings both apply; Claude Code doesn’t silently drop one. Every other key follows strict override (higher scope wins, full stop).

Managed settings can’t be overridden by anything below them. If your org pushes forceLoginMethod: "oauth", no .claude/settings.local.json on any laptop changes that.

Fields by category

Model and session behavior

Permissions and sandboxing

This is the part worth reading twice if you’ve deployed sandbox.credentials — it’s the newest and least-documented category, and it’s the one that actually stops a leaked .env from reaching a tool call rather than just warning about it after the fact.

Hooks and automation

Hook syntax and payloads are documented separately — see our Hooks reference for the event schema. This table only covers the settings.json keys that turn hooks on or off.

MCP and plugins

Worth flagging since it trips people up: MCP servers are not configured in settings.json. They live in ~/.claude.json (user), .mcp.json (project), or managed-mcp.json (managed). The keys above only control which of those servers are allowed to load — not what they connect to.

Memory and context

Git and attribution

Auth and identity

Interface and notifications

Cleanup, updates, and misc

A worked example: what actually wins

Say your org’s managed settings deny Bash(curl *). Your project .claude/settings.json doesn’t mention curl at all. Your local .claude/settings.local.json has "allow": ["Bash(curl *)"] because you added it while debugging.

What happens when Claude Code tries to run curl?

It’s blocked. Managed deny rules can’t be overridden by allow rules anywhere below them — remember, permission rules merge rather than override, and a deny always wins over an allow when both match the same pattern. Your local allow entry does nothing here except confuse you into thinking it should have worked.

This is the single most common support question in Claude Code permission threads: “I added an allow rule and it’s still blocked.” The answer is almost always a managed or project-level deny sitting above it in the merge.

Minimal example that touches most categories

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "outputStyle": "fullscreen",
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": true,
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Bash(curl *)", "Read(./.env)", "Read(./.env.*)"]
  },
  "sandbox": {
    "credentials": {
      "files": [{ "path": ".env", "mode": "deny" }]
    }
  },
  "hooks": {
    "beforeToolCall": [
      { "type": "http", "url": "https://hooks.example.com/before" }
    ]
  }
}

Commit this as .claude/settings.json. Anything personal — your preferred editorMode, a local allow rule for a command only you run — belongs in .claude/settings.local.json, which should already be in your .gitignore.

FAQ

Where do I put MCP server config? Not in settings.json. Use .mcp.json (project, git-tracked) or ~/.claude.json (user). settings.json only holds allow/deny lists for which servers are permitted to load.

Which file should I commit to git? .claude/settings.json (project scope). Never commit .claude/settings.local.json — it’s meant to be machine-specific and Claude Code auto-adds it to .gitignore when it’s created.

Do permission rules override or merge? They merge. allow, deny, and ask arrays from every applicable scope are concatenated, and deny wins over allow on a matching pattern.

What’s the difference between disableAutoMode and permissions.disableAutoMode? Same effect (turns off auto mode), different location — one is a top-level key, the other lives inside the permissions object. Both accept the string "disable".

Can I restrict which models a user can pick? Yes — availableModels restricts the picker, and enforceAvailableModels: true extends that restriction to the default model as well.

How do I stop a settings.local.json field from being accidentally committed? Claude Code gitignores it automatically when the file is first created. If it’s already tracked, remove it with git rm --cached .claude/settings.local.json and add the pattern to .gitignore manually.

Browse real project configurations — not just field lists — in our rules gallery, including settings.json examples pulled from open-source repos that use hooks, sandboxing, and managed permission rules in production.