- Home
- Learn
- Deep Dives
- Claude Code settings.json: Full Configuration Reference
Claude Code settings.json: Full Configuration Reference
Where Claude Code settings.json lives, which file wins, how permissions and hooks work, plus two settings files you can paste. Checked 16-11-2026.
Published 16-11-2026. Last verified on 16-11-2026 against the Claude Code documentation; we re-check this page monthly, because new settings keys arrive with almost every Claude Code release.
Quick answer: what is settings.json and which file should you edit?
This reference is for developers and engineering leads who set up Claude Code for themselves and a team of two to twenty people, and who need to know which file to edit, which value wins and what a safe shared configuration looks like. The Claude settings.json file is the JSON file where Claude Code reads its configuration: permissions, model, environment variables, hooks, sandbox rules and around two hundred other options. There are four places it can live. Your personal defaults go in ~/.claude/settings.json. Rules your whole team shares go in .claude/settings.json inside the repository, which you commit. Your private overrides for one project go in .claude/settings.local.json, which stays out of git. Organisation-wide policy goes in a managed settings file that users cannot override. When the same key is set in several places, managed settings win, then the command line, then local, then project, then user. Lists such as permission rules are merged across files instead of replaced.
How we built this reference
Our method in three lines: every key, path and rule on this page is taken from the official Claude Code documentation as we read it on 16-11-2026; behaviour we did not run ourselves is labelled "documented, not verified by us"; and where a popular guide contradicts the docs, we follow the docs and say so.
Our gate for this page: a key or behaviour only appears here if it is in the Claude Code settings, settings reference, permissions or managed settings docs on the date above. The briefing asked us to verify every key in a live install. That was not possible in this production run, so nothing on this page is tested by us; the two files further down are built only from keys and syntax shown in the official examples.
The gate removed four things that rank well elsewhere. A top-level allowedTools key, a smallModel key, an apiBaseUrl key and a CLAUDE_MODEL environment variable are all presented in a third-party guide that sits in the top three for "claude settings.json", and none of them appears in the official settings index we read. The same guide says arrays from different files replace each other. The docs say the opposite: lists merge. We left all of it out.
In our count of the official settings reference index on 16-11-2026 there were 247 entries: 185 top-level keys and 62 nested keys such as permissions.deny or sandbox.network.allowedDomains. We think a full list of 247 keys helps nobody set up a team, so we group the ones that matter by job and link the official index for the rest.
Where does Claude Code settings.json live?
Claude Code reads settings from four scopes, and each one has a fixed path. These are the paths from the Claude Code docs on 16-11-2026:
| Scope | Path | Who it affects | Goes in git? |
|---|---|---|---|
| User | ~/.claude/settings.json | You, in every project on this machine | No |
| Shared project | .claude/settings.json in the repo | Everyone who opens the folder | Yes, commit it |
| Project local | .claude/settings.local.json in the repo | You, in this project only | No |
| Managed | managed-settings.json in a system folder | Everyone on the machine or in the organisation | Deployed by IT |
On Windows the user file sits in the same place under your home folder: C:\Users\you.claude\settings.json. The managed file has its own path per operating system:
- macOS: /Library/Application Support/ClaudeCode/managed-settings.json
- Linux and WSL: /etc/claude-code/managed-settings.json
- Windows: C:\Program Files\ClaudeCode\managed-settings.json
For larger teams, the part we would read twice is the managed settings docs, which add three other delivery routes for organisations: a macOS configuration profile in the com.anthropic.claudecode domain, a Windows registry value under HKLM\SOFTWARE\Policies\ClaudeCode and server-managed settings pushed from the Claude admin console. According to the docs, server-managed settings are fetched at startup and polled hourly, and MDM and registry sources are checked every 30 minutes. The older C:\ProgramData\ClaudeCode path on Windows is no longer read, which is the first thing we would check if a Windows policy suddenly stops applying.
One more file causes confusion: ~/.claude.json, without the folder. It holds account details, per-project state, MCP server configuration and the global options that the /config menu writes. It is not a settings.json and you rarely edit it by hand. If you document these paths for a team wiki, the technical documentation collection has skills that keep such pages in sync with the repository.
Which settings file wins?
When a key is set in more than one file, Claude Code uses this order, highest first, as stated in the Claude Code settings docs:
- Managed settings. First because this is the organisation's policy; nothing a user does can override it.
- Command line. Second because a --settings flag or a CLI argument is a deliberate choice for one session.
- Project local (.claude/settings.local.json). Third because it is your private override for this repository.
- Shared project (.claude/settings.json). Fourth because it is the team default that a person may need to adjust locally.
- User (~/.claude/settings.json). Last because it is the general fallback for every project.
Two details change how this plays out in practice, and we think both deserve more attention than most guides give them.
First, lists merge instead of overriding. If your user file allows Bash(git diff *) and the project file allows Bash(npm run *), both rules apply. A deny rule in any scope is evaluated before an allow rule in any scope, so a team can block reading .env in the project file and no personal allow rule will open it again. The docs name a few exceptions that take the whole value from a single file, among them fallbackModel, modelPicker and availableModels.
Second, environment variables are not a level in this order, but some of them still win. The docs say ANTHROPIC_MODEL overrides the model key for that session, while ANTHROPIC_DEFAULT_MODEL only applies when no file sets model. A managed model value is a default, not a lock: a user can still pick another model unless availableModels restricts the list.
Our advice: put as little as possible in user settings, put team rules in the shared project file and reserve managed settings for the handful of rules that must hold on every laptop.
settings.json vs settings.local.json: what goes where?
The difference is who sees the file. .claude/settings.json is shared and committed, so it carries the rules every teammate needs. .claude/settings.local.json is personal, and the docs say Claude Code adds it to your global git excludes the first time it writes the file in a repository. If you create it by hand, add it to .gitignore yourself.
Our split for a typical product team, and the order in which we would fill the files:
- Shared settings.json: permission rules for build and test commands, deny rules for secrets, hooks the team relies on, the sandbox block and enabled plugins. It goes first because a rule that only lives on one laptop protects nobody else.
- settings.local.json: a different model for your own experiments, extra allow rules for scripts only you run and local paths that differ per machine. Second because these are preferences, not policy.
- User settings.json: editor mode, theme, status line and notification channel. Last because none of it belongs to a project.
People also mix up settings.json and CLAUDE.md. settings.json controls what Claude Code is allowed to do and how it runs; CLAUDE.md tells Claude how to work in your codebase. Our CLAUDE.md templates cover the second file. When the instruction file grows, Context Lint, free, reads CLAUDE.md and AGENTS.md and reports contradictions, duplicates, dead paths and the token cost per session.
How does the permissions block work?
The permissions block decides which tools Claude may use without asking. It takes three lists of rules (allow, ask and deny), plus additionalDirectories and defaultMode. The permissions docs state the order plainly: rules are evaluated deny first, then ask, then allow. The first match decides. Specificity does not change that order, which is why a broad deny always beats a narrow allow.
A rule is a tool name with an optional pattern in brackets. Examples from the docs:
- Bash(npm run build) matches that exact command; *Bash(npm run ) matches every npm script.
- Read(./.env) and Read(./secrets/)** cover single files and whole folders.
- WebFetch(domain:example.com) limits web fetches to one domain.
- mcp__* as a deny rule blocks every MCP tool; an allow rule needs the literal mcp__servername__ prefix.
Path patterns have anchors: //path is absolute, ~/path is your home folder, /path is relative to the settings file it sits in and ./path is relative to the working directory. The docs also note that rules for Write, NotebookEdit and Glob never match; use Edit and Read rules for file access instead. That one catches a lot of hand-written configs.
defaultMode sets the starting permission mode. The documented values are default, acceptEdits, plan, auto, dontAsk and bypassPermissions. The settings docs say auto and bypassPermissions do not take effect from project or local settings, only from user or managed settings or a flag for one session. To stop anyone using bypass mode, a managed file sets permissions.disableBypassPermissionsMode to "disable". Our Claude Code permissions guide explains when YOLO mode is defensible and when it is not.
One more rule we rely on: allow rules and additionalDirectories in a shared project file only apply after you trust the folder, while deny and ask rules apply at once. That protects you from a cloned repository that tries to allow itself everything.
Permissions only cover Claude Code's own tools, and we see teams forget that. If your team also builds agents that call tools, Agent Guardrails: Prompt-Injection and Exfiltration Defense, $15, adds an allow, ask and deny policy gate for agent tool calls plus PII redaction. The security collection has more skills for that layer.
Which model, env and effort keys matter?
In our view six keys cover most of what teams set here. Their behaviour as documented on 16-11-2026:
| Key | Accepts | What it does |
|---|---|---|
| model | an alias or model ID | Default model for sessions; --model and ANTHROPIC_MODEL override it |
| availableModels | array of aliases or IDs | Limits which models people can pick; a managed list applies as written |
| enforceAvailableModels | true or false | Makes the availableModels list binding (documented from v2.1.175) |
| effortLevel | low, medium, high, xhigh | Default effort for models without a saved level |
| maxEffortLevel | low to max | Caps effort; max means no cap (documented from v2.1.267) |
| env | object of name and value pairs | Environment variables for every session and its subprocesses |
The search "claude code settings.json availablemodels schema" comes up often, so the short version: availableModels is a plain array such as ["opus", "sonnet"], matching is by prefix unless a managed file sets availableModelsMatch to "exact", and the list only becomes a hard limit when enforceAvailableModels is true. modelSettings lets you store a separate effortLevel per model, which we prefer over one global level because a fast model and a deep model rarely need the same setting.
For env, our rule is simple: keep secrets out of it. The file is plain text and the shared version is in git. Put API credentials behind apiKeyHelper, which runs your own command to fetch the key, or in your shell. The docs also say telemetry export variables set in project or local env are ignored, apart from a few values that switch things off.
Choosing the model itself is a cost question more than a settings question. The LLM ops collection has skills for routing work to cheaper models and tracking spend per run.
How do you add hooks in settings.json?
Hooks run your own command at fixed points in Claude Code's lifecycle, and they live in the hooks key. The structure is: event name, then a list of matchers, then the commands to run. This is the example from the official settings example page, which runs a script before every Bash call:
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
]
}
]
}
We use ${CLAUDE_PROJECT_DIR} rather than a relative path so the hook works from any subfolder. Organisations can restrict hooks with the managed keys allowManagedHooksOnly and disableAllHooks, and allowedHttpHookUrls limits where HTTP hooks may send data. We would always set at least one of those in a managed file, because a hook is a shell command that runs without asking.
Our Claude Code hooks guide covers every event with working scripts. If your hooks call external tools or MCP servers, Tool Safety Scan, free, reads tool definitions and reports hidden instructions and ungated actions. More automation patterns sit in the workflow automation collection.
Two settings files you can paste
Both files below use only keys and syntax shown in the official Claude Code example page on 16-11-2026. We have not run them in a fresh install, so check /status and /permissions after you paste them.
File 1: solo developer, ~/.claude/settings.json. For one person who wants fewer prompts on safe commands and a default model with a higher effort level.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "sonnet",
"effortLevel": "high",
"permissions": {
"allow": [
"Bash(git diff *)",
"Bash(git status)",
"Bash(npm run *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
},
"cleanupPeriodDays": 20
}
File 2: locked-down team, .claude/settings.json. For a team of five to twenty that commits one file, blocks secrets, asks before every push and runs Bash in a sandbox with a short list of allowed domains.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run *)"],
"ask": ["Bash(git push *)"],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
]
}
]
},
"sandbox": {
"enabled": true,
"network": {
"allowedDomains": ["registry.npmjs.org", "github.com"]
}
}
}
For the second file you also write the block-rm.sh script the hook calls; we left its contents out because every team blocks different commands. If the same team runs Claude Code in CI, harden the workflow files too: GitHub Actions Hardener, $12, checks .github/workflows against 19 rules, gives a score from 0 to 100 and pins actions to commit SHAs. Our Claude Code sandbox guide explains the sandbox block in depth, and the DevOps and cloud collection has skills for the deployment side.
Why is my setting not applied?
The settings docs have a troubleshooting section for settings that do not apply. From what it describes, we would check these five causes, in this order:
- A higher scope sets the same key. First because it is the most common: a value in settings.local.json or a managed file silently beats your project file. /status shows which sources loaded.
- An environment variable overrides it. Second because ANTHROPIC_MODEL in a shell profile beats the model key and is easy to forget.
- The mode cannot be set from that file. Third: auto and bypassPermissions in a project or local file have no effect, by design.
- The rule never matches. Fourth: a Write(...) rule or a wrong path anchor looks valid but does nothing.
- The JSON is invalid. Last because Claude Code reports it, but a trailing comma still costs people an afternoon.
The same audit habit applies to the other config file next to settings.json. MCP Config Audit, free, reads an mcp.json and reports unpinned packages, tokens in the file, plain HTTP endpoints and auto-approved actions. For broader reviews of configuration and code, see the code quality and review collection.
How do you validate your settings file?
We start every settings file with the $schema line from our two files, and we would add it to yours. Editors such as VS Code then flag unknown keys and wrong value types while you type. The settings docs warn that the schema can lag behind new releases, so a brand-new key may show as unknown while it works fine.
Then check what Claude Code actually loaded. Per the settings reference and the settings docs:
- /status lists the setting sources that loaded, with the managed source in brackets, such as (file), (plist) or (remote).
- /permissions lists every permission rule and the file it came from.
- claude doctor lists entries that were rejected.
/status does not show which file supplied each individual key. That is our main complaint about it, so for a disputed value we read the files top-down in the precedence order above.
Your next step
Our recommended order is to start with the shared project file: commit the deny rules for secrets and the ask rule for git push, then add personal preferences in your user file. Once the team file is in place, our guide to building a Claude Code skill for your team shows how to share skills the same way. Before you hand the setup to a wider group, Agent Security Review Pack, $14.99, scores the surfaces an injected instruction can reach in an agent repository.
We sell skills that Claude Code and other agents load through one connection to Agensi (see the MCP setup guide), and we name ours in the sections above. No vendor paid to be listed.
Written by Samuel Rose, Founder of Agensi. Next scheduled review: 16-12-2026.