Claude Code settings.json validator
Published · Last updated · Docs checked 2026-11-12
Claude Code reads settings.json from ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json. Each is strict JSON. Permission rules look like Tool or Tool(specifier), env holds string values, and hooks nest event, matcher group, then handler. Paste yours below to check it.
Validate your settings.json
Runs in your browser. Nothing you paste or drop is uploaded or stored. No AI model reads it.
Results show here as soon as there is something to check.
A Claude Code settings.json example
This is the example on Anthropic's settings page, copied as written. It lets Claude Code run your lint and test commands without asking and stops it reading .env files. It passes every check here.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}
The $schema line gives you autocomplete in editors that read JSON schema. For a personal file, a team file and an organization file with every key explained, see Anthropic's example settings files.
Where is settings.json?
From Settings files and who they affect:
| Scope | File | Who it affects |
|---|---|---|
| User | ~/.claude/settings.json | You, in every project on this machine |
| Shared project | .claude/settings.json | Everyone working in the folder that contains it. Commit it in git. |
| Project local | .claude/settings.local.json | You, in this one project only. Keep it out of git. |
| Managed | managed-settings.json and other managed sources | Everyone your organization deploys it to |
A fifth file, ~/.claude.json, holds your account, MCP server configs and a short list of global config keys. Claude Code writes it itself. When the same key is in more than one file, the settings precedence rules pick the value.
Permissions, env and hooks: the shapes the docs give
Permissions
"Permission rules follow the format Tool or Tool(specifier)" (Permission rule syntax). A trailing * matches the rest of a command. Put the * after the subcommand: Bash(git log *) allows only git log, while Bash(git *) allows every git command. MCP tools are named mcp__server__tool, and an MCP rule with parentheses is skipped.
{
"permissions": {
"allow": ["Bash(npm run *)"],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)"],
"defaultMode": "acceptEdits"
}
}env
An object that maps variable names to string values (env). Write "1", not 1.
{
"env": {
"DISABLE_AUTO_COMPACT": "1",
"ANTHROPIC_BASE_URL": "https://proxy.example.com"
}
}Hooks
Three levels: a hook event such as PreToolUse, a matcher group that filters it, and one or more handlers with a type of command, http, mcp_tool, prompt or agent (Hooks: Configuration). The docs list 33 events as of 2026-11-12.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/check-bash.sh" }
]
}
]
}
}The env, permissions and hooks examples are copied from the settings reference.
What it checks
A problem means Claude Code rejects the file or the value has the wrong type. A warning means Claude Code skips, ignores or never matches the entry, or the docs do not list it. A tip is worth a look. A key the docs do not list is reported as "not in the docs as of 2026-11-12", since it may be newer than the docs.
| Check | What the docs say |
|---|---|
| Strict JSON, with the line and column of the first error | "Settings files are strict JSON: a // comment or a trailing comma is a syntax error, and Claude Code reports the file as a Settings Error at the next start." Settings: Edit a settings file |
| The same key twice in one object | "The names within an object SHOULD be unique." RFC 8259, section 4 (Objects) |
| Top-level keys the settings reference does not list | "This reference page lists each key Claude Code reads from a settings file, plus the short group of keys it keeps in ~/.claude.json instead." All settings: Settings index |
| Keys that belong in ~/.claude.json instead | "Save these keys in ~/.claude.json, not in a settings file. Claude Code ignores them anywhere else." All settings: Global config settings |
| Keys set in a file the docs say ignores them | "Scope lists the files it can go in: User is ~/.claude/settings.json, Project is .claude/settings.json, Local is .claude/settings.local.json, and Managed is what your organization deploys." All settings: Settings index |
| Keys the settings index marks as deprecated | "This reference page lists each key Claude Code reads from a settings file, plus the short group of keys it keeps in ~/.claude.json instead." All settings: Settings index |
| permissions is an object with documented keys and string arrays | "Type: object with allow, ask, deny, additionalDirectories, blockReadsOutsideWorkingDirectories, blockWritesOutsideWorkingDirectories, defaultMode, denyInsteadOfPrompting, disableBypassPermissionsMode, and disableAutoMode" All settings: permissions |
| Each rule is Tool or Tool(specifier) | "Permission rules follow the format Tool or Tool(specifier). Parentheses inside the specifier are literal, so a command or path that contains them needs no escaping." Permissions: Permission rule syntax |
| Tool names match the tools reference | "A deny or ask rule whose tool name matches no known tool produces a startup warning to catch typos. Tool names containing _ or * are exempt from the check, and so are the names of tools Claude Code has removed, such as TaskOutput." Permissions: Tool name wildcards |
| Rules Claude Code skips or never matches | "An unanchored allow glob such as "*", "B*", or "mcp__*" is skipped and doesn't auto-approve anything." Permissions: Tool name wildcards |
| The same rule in allow and in deny or ask | "Claude Code evaluates deny rules first, then ask, then allow, and the first match decides regardless of how specific each rule is" All settings: Permission rule syntax |
| permissions.defaultMode is a documented mode | "Type: string, one of: "default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions", "manual"" All settings: permissions.defaultMode |
| env is an object of string values | "Type: object mapping variable names to string values" All settings: env |
| Hook event names match the hooks reference | "Settings Warning: only individual entries fail, such as a malformed permission rule or an unknown hook event name. Claude Code skips those values and keeps the rest of the file in effect." Hooks: Hook lifecycle |
| Each event holds matcher groups with a hooks array | "Type: object keyed by hook event; each value is an array of { "matcher", "hooks" } groups whose hooks entries have a type of "command", "prompt", "agent", "http", or "mcp_tool"" All settings: hooks |
| Each handler has a known type and its required fields | "type | yes | "command", "http", "mcp_tool", "prompt", or "agent"" Hooks: Common fields |
| model is a string, and not a near miss of an alias | "Either of these warnings means Claude Code doesn't recognize the model ID you set, and the ID nearly spells a model name or alias it does recognize" Model configuration: Fix a mistyped model name |
How it works
- A small JSON parser reads the text and keeps the position of every key and value. On a syntax error it stops and names the line and column, with a hint for the common cases: a
//comment, a trailing comma, a missing comma, single quotes, an unquoted key. - It compares each top-level key with the 186 keys in the settings index and their scope column. If you say which file you pasted, it also flags keys the index says that file ignores.
- Each permission rule is split into a tool name and an optional specifier. The tool name is matched against the 46 tools in the tools reference, and the rule against the cases the permissions page says Claude Code skips or never matches.
env,hooksandmodelare checked against their entries in the settings reference, the hooks reference and the model aliases table.- The key list, hook events, tool names and aliases were read from the docs' Markdown on 2026-11-12 by a script in the site's repo. The sha256 of each page is listed under Sources, so you can tell whether a page has changed since.
What it does not check
- The values of most keys, such as
sandbox,statusLineorattribution. Open the key in the settings reference for its type. - Whether your scripts, paths and MCP servers exist. It sees only the text you paste.
- Full model IDs. Any ID that starts with claude- passes, and gateway or cloud IDs are not checked.
- How files combine. Run
/statusto see which files loaded andclaude doctorfor the entries Claude Code dropped.
All 186 settings keys in the docs
Every top-level key in the settings index as of 2026-11-12, with its scope. Dotted keys such as permissions.allow nest under their parent.
Show the key list
| Key | What it does | Scope |
|---|---|---|
| advisorModel | Pick which model answers when Claude asks the advisor tool | Any file |
| agent | Start every session as a named subagent with its prompt, tools, and model | Any file |
| agentPushNotifEnabled | Let Claude send a push notification to your phone when it decides to | Any file |
| allowAllClaudeAiMcps | Load the claude.ai connectors Claude Code fetches itself alongside a deployed managed-mcp.json | Managed |
| allowClaudeInChromeWithManagedMcp | Let the built-in Claude in Chrome server run alongside a deployed managed-mcp.json | Managed |
| allowedChannelPlugins | Replace the default allowlist of channel plugins that can push messages | Managed |
| allowedHttpHookUrls | Limit which URLs HTTP hooks can target | Any file |
| allowedMcpServers | Allowlist which MCP servers users can add | Any file |
| allowedProviders | Limit which API providers a machine may use | Managed |
| allowManagedHooksOnly | Run only the hooks your organization deploys | Managed |
| allowManagedMcpServersOnly | Make the managed MCP allowlist the only one that applies | Managed |
| allowManagedPermissionRulesOnly | Make managed settings the only settings source of permission rules | Managed |
| alwaysThinkingEnabled | Turn extended thinking off for every session | Any file |
| apiKeyHelper | Generate the API credential with your own command | Any file |
| askUserQuestionTimeout | Let an unanswered question auto-continue after idle time | User or managed |
| appendPlugins | Run your organization's mods after every mod a user installs | User or managed |
| attribution | Customize the attribution Claude Code adds to commits and pull requests | Any file |
| autoCompactEnabled | Turn automatic compaction off or on | Any file |
| autoCompactWindow | Set how full the context gets before Claude Code compacts | Any file |
| autoConnectIde | Connect to a running VS Code or JetBrains IDE automatically from an external terminal | Global config |
| autoContinueAtUsageLimit | Wait in the open session and continue the task automatically after a claude.ai usage limit resets | User or managed |
| autoInstallIdeExtension | Let /ide install the IDE extension from an external terminal | Global config |
| autoMemoryDirectory | Store auto memory in a directory you choose | Any file |
| autoMemoryEnabled | Turn auto memory off or on | Any file |
| autoMode | Add your own allow and deny rules to the auto mode classifier | User or managed |
| autoScrollEnabled | Follow new output to the bottom in fullscreen rendering | Any file |
| autoUpdatesChannel | Follow the stable release channel instead of latest | Any file |
| availableModels | Restrict which models people can pick | Any file |
| availableModelsMatch | Make each availableModels model ID entry permit only the version it names | Managed |
| awaySummaryEnabled | Turn off the session recap shown when you come back to the terminal | Any file |
| awsAuthRefresh | Refresh expired Bedrock credentials in .aws with your own command | Any file |
| awsCredentialExport | Supply Bedrock credentials as JSON from your own command | Any file |
| axScreenReader | Render screen-reader friendly output | User or managed |
| bashEditDiffEnabled | Record the files that changed while a Bash command ran in every permission mode | User or managed |
| bashOutputMaxChars | Set how much of a successful command's output Claude receives inline | Any file |
| blockedMarketplaces | Block plugin marketplace sources for your organization | Managed |
| browserExternalPageTools | Keep Claude's tools off external pages in the desktop Browser pane | Managed |
| channelsEnabled | Allow channels for your organization | Managed |
| claudeInChromeDefaultEnabled | Turn on Chrome integration when a session starts, in the interactive CLI and the VS Code extension | Global config |
| claudeMd | Inject organization-wide CLAUDE.md instructions from managed settings | Managed |
| claudeMdExcludes | Skip specific CLAUDE.md files when memory loads | Any file |
| cleanupPeriodDays | Choose how many days Claude Code keeps transcripts before deleting them | Any file |
| companyAnnouncements | Show your organization's announcements at startup | Any file |
| copyFullResponse | Make /copy copy the full response without showing the picker | Global config |
| copyOnSelect | Turn off automatic copying of text you select with the mouse in fullscreen rendering and agent view | Global config |
| crossSessionInbound | Choose whether Claude Code delivers messages from your other sessions, shows a notice without delivering them, or refuses them | Any file |
| defaultShell | Choose whether Bash or PowerShell runs the shell commands you type with the ! prefix | Any file |
| defaultToAgentsView | Open agent view instead of a new conversation when you run claude with no arguments | Global config |
| deniedMcpServers | Block specific MCP servers by URL, command, or name | Any file |
| deniedModels | Block specific models, even ones availableModels permits | Managed |
| desktopSessionCleanupPeriodDays | Set an age limit in days for Claude Desktop and Cowork transcripts | User or managed |
| dialogExpiry | Set how long Claude Code waits for Remote Control or an SDK host to answer a forwarded dialog before it cancels the dialog | User or managed |
| diffTool | Choose whether Claude's proposed file changes open in the VS Code or JetBrains diff viewer or stay in the terminal | Global config |
| disableAgentView | Turn off background agents and agent view | Any file |
| disableAllHooks | Turn off hooks, a custom status line, and a custom @ file suggestion command at once | Any file |
| disableArtifact | Deprecated; use enableArtifact to turn the Artifact tool off | Any file |
| disableAutoMode | Remove auto mode from the permission mode cycle | Any file |
| disableBrowserExternalNavigation | Limit the desktop Browser pane to localhost for people and Claude | Managed |
| disableBundledSkills | Turn off the skills and workflows included with Claude Code | Any file |
| disableClaudeAiConnectors | Turn off claude.ai connectors so Claude Code doesn't fetch them | Any file |
| disableCommandPluginSources | Block plugins that install by running a marketplace-declared command | Managed |
| disableDeepLinkRegistration | Stop Claude Code from registering the claude-cli:// handler | Any file |
| disableDesktopLocalSessions | Turn off Desktop Code sessions that run on the device, leaving SSH to other hosts and cloud | Managed |
| disabledMcpjsonServers | Reject specific servers from a project's .mcp.json | Any file |
| disableMobileSimulatorTools | Block Claude's tools in the desktop iOS Simulator pane | Managed |
| disableRemoteControl | Turn off Remote Control everywhere it can start | Any file |
| disableRemotePreviewScripts | Turn off scripts in the desktop app's HTML previews in SSH and WSL sessions | Managed |
| disableSideloadFlags | Reject the CLI flags that sideload plugins, subagents, and MCP servers | Managed |
| disableSkillShellExecution | Stop skills and custom commands from running inline shell | Any file |
| disableWorkflows | Turn dynamic workflows off for everyone; use enableWorkflows for yourself | Any file |
| editorMode | Use vim key bindings in the input prompt | Any file |
| effortLevel | Set a default effort level for models without a saved level of their own | Any file |
| emojiCompletionEnabled | Turn off :shortcode: emoji suggestions and replacement in the prompt input | Any file |
| enableAllProjectMcpServers | Approve every server in project .mcp.json files without a prompt | Any file |
| enableArtifact | Turn the Artifact tool off with a false in any file; no file can turn it back on | Any file |
| enabledMcpjsonServers | Approve specific servers from a project's .mcp.json | Any file |
| enabledPlugins | Turn individual plugins on or off per scope | Any file |
| enableWorkflows | Turn dynamic workflows on or off against your plan's default | Any file |
| enforceAvailableModels | Keep the /model Default choice inside your availableModels allowlist | Any file |
| env | Set environment variables for every session and its subprocesses | Any file |
| externalEditorContext | Show Claude's last response as comments when you press Ctrl+G to edit | Global config |
| extraKnownMarketplaces | Register marketplaces for a repository or an organization | Any file |
| fallbackModel | Name backup models for when the primary is overloaded | Any file |
| fastMode | Turn fast mode on for sessions where it's available | Any file |
| fastModePerSessionOptIn | Require people to turn fast mode on each session | Any file |
| feedbackDrafts | Control whether Claude queues feedback drafts for you to review | User or managed |
| feedbackSurveyRate | Change how often the session quality survey appears | Any file |
| fileCheckpointingEnabled | Turn off or on the file snapshots that /rewind restores | Any file |
| fileSuggestion | Supply @ file autocomplete from your own command | Any file |
| footerLinksRegexes | Make issue or review IDs in output into clickable links below the input box | User or managed |
| forceLoginGatewayUrl | Set the gateway URL the login screen connects to | User or managed |
| forceLoginMethod | Restrict login to claude.ai, Claude Console, or a cloud gateway | Any file |
| forceLoginOrgUUID | Pin claude.ai logins to your organization; only managed settings enforce it | Any file |
| forceRemoteSettingsRefresh | Block startup until server-managed settings are freshly fetched | Managed |
| gatewayInternalNetworks | Let /login reach a cloud gateway on public IPv4 space your organization uses internally | Managed |
| gcpAuthRefresh | Refresh Google Cloud credentials with your own command | Any file |
| hooks | Run your own commands as hooks at points in Claude Code's lifecycle | Any file |
| httpHookAllowedEnvVars | Limit which env vars HTTP hooks can put in headers | Any file |
| idleCompaction | Stop Claude Code from compacting a long conversation that you've stepped away from | Any file |
| includeCoAuthoredBy | Deprecated; use attribution to hide or change commit and PR attribution | Any file |
| includeGitInstructions | Remove the built-in commit and PR instructions from Claude's context | Any file |
| inputNeededNotifEnabled | Get a push notification when Claude is waiting on you | Any file |
| isolatePeerMachines | Ask you before Claude messages one of your sessions on another machine | Any file |
| keybindingFlavor | Deprecated and has no effect; the word-editing shortcuts always follow readline conventions | Any file |
| language | Have Claude respond in a language other than English | Any file |
| leftArrowOpensAgents | Turn off the ← shortcut that backgrounds the session and opens agent view | Global config |
| managedMcpServers | Provide remote MCP servers to every user alongside the ones they add | Managed |
| managedSourcesBehavior | Compose every managed source you deploy instead of using the highest-priority one alone | Managed |
| maxEffortLevel | Cap the effort level for every model or per model, on every provider | Any file |
| maxProseWidth | Cap how wide the prose in Claude's responses runs in a wide terminal | Any file |
| minimumVersion | Keep auto-updates from installing anything below a version | Any file |
| model | Change the model Claude Code starts with | Any file |
| modelOverrides | Map model IDs to your provider's IDs, such as Bedrock ARNs | Any file |
| modelPicker | Choose which models the /model picker lists, in your own order and with your own labels | User or managed |
| modelPricing | Report spend at your organization's contracted rates instead of list price | Managed |
| modelSettings | Keep a saved effort level or auto-compact window per model, or cap one model's effort | Any file |
| otelHeadersHelper | Generate rotating OpenTelemetry headers with your own command | Any file |
| outputStyle | Change Claude's role, tone, and output format with an output style | Any file |
| parentSettingsBehavior | Apply or drop restrictions an SDK or IDE host passes when you deploy managed settings | Managed |
| permissionExplainerEnabled | Removed in v2.1.257, together with the Ctrl+E command explanation on shell permission prompts | Global config |
| permissions | Set allow, ask, and deny rules and the default permission mode | Any file |
| plansDirectory | Choose where plan mode writes plan files | Any file |
| pluginConfigs | Store the answers you gave a plugin's configuration dialog | User or managed |
| pluginSuggestionMarketplaces | Choose which marketplaces can surface plugin install suggestions in /plugin | Managed |
| pluginTrustMessage | Add your own text to the plugin trust warning | Managed |
| policyHelper | Run an executable that computes managed settings at startup | Managed |
| preferredNotifChannel | Choose a terminal bell or desktop notification for task completion | Any file |
| prefersReducedMotion | Reduce or turn off spinner, shimmer, and flash animations | Any file |
| prependPlugins | Run your organization's mods before every mod a user installs | User or managed |
| processWrapper | Run Claude Code's background processes through a corporate launcher on macOS and Linux | User or managed |
| promptCacheTtl | Choose the prompt cache lifetime for the main conversation | Any file |
| promptSuggestionEnabled | Hide the grayed-out prompt suggestions in the input box | Any file |
| prStatusFooterEnabled | Turn off the prompt footer's PR review status badge and the pull request check behind it | Global config |
| prUrlTemplate | Point PR links at an internal code-review tool instead of github.com | Any file |
| remoteControlAtStartup | Connect Remote Control automatically when a session starts | Any file |
| requiredMaximumVersion | Refuse to start on a version newer than your organization allows | Managed |
| requiredMinimumVersion | Refuse to start on a version older than your organization requires | Managed |
| respectGitignore | Keep gitignored files out of the @ file picker | Any file |
| respondToBashCommands | Stop Claude from responding after a ! shell command runs | Any file |
| sandbox | Isolate Bash commands from your filesystem and network on macOS, Linux, and WSL2 | Any file |
| showClearContextOnPlanAccept | Show a "clear context" option on the plan accept screen | Any file |
| showThinkingSummaries | See summaries of Claude's thinking instead of a collapsed stub | Any file |
| showTurnDuration | Hide the "Cooked for" duration after each response | Any file |
| skillListingBudgetFraction | Reserve more or less context for the skill listing | Any file |
| skillListingMaxDescChars | Cap each skill's description length in the skill listing | Any file |
| skillOverrides | Hide or collapse a skill without editing its SKILL.md | Any file |
| skipAutoPermissionPrompt | Skip the one-time notice Claude Code shows when you first enter auto mode yourself rather than through the built-in default | User or managed |
| skipDangerousModePermissionPrompt | Skip the confirmation dialog before bypassPermissions mode | User, local, or managed |
| skipWebFetchPreflight | Skip the WebFetch hostname check when Anthropic is unreachable | Any file |
| spellcheck | Underline misspelled words in the prompt input with a spell checker you install | User or managed |
| spinnerTipsEnabled | Hide tips in the spinner while Claude works | Any file |
| spinnerTipsOverride | Add your own tips to the spinner rotation, or replace the built-in tips | Any file |
| spinnerVerbs | Add or replace the verbs shown while a turn runs | Any file |
| sshConfigs | Add SSH connections to the Desktop environment selector | User or managed |
| sshHostAllowlist | Limit which hosts Desktop SSH sessions can reach | Managed |
| sshHostCommands | Add SSH connections whose host comes from a command to the Desktop environment selector | User or managed |
| statusLine | Run your own command to render a status line below the prompt | Any file |
| strictKnownMarketplaces | Allowlist the marketplace sources users can add and install from | Managed |
| strictPluginOnlyCustomization | Block skills, agents, hooks, and MCP servers from user and project sources | Managed |
| subagentPromptCacheTtl | Choose the prompt cache lifetime for subagents and other requests outside the main conversation | Any file |
| subagentStatusLine | Rewrite rows in the subagent task display with your own command | Any file |
| switchModelsOnFlag | Switch models automatically or pause when a safety classifier flags a request | Any file |
| syncClaudeAiPlugins | Stop loading the plugins enabled on your claude.ai account and stop downloading new ones | User, local, or managed |
| syncClaudeAiSkills | Stop loading the skills enabled on your claude.ai account and stop downloading new ones | User, local, or managed |
| syntaxHighlightingDisabled | Turn off syntax highlighting in diffs and code blocks | Any file |
| taskOutputMaxChars | Removed in v2.1.277, together with the TaskOutput tool it sized | Any file |
| teammateDefaultModel | Removed in v2.1.234; see Specify teammates and models for how Claude Code picks a teammate's model | Global config |
| teammateMode | Choose how agent team teammates display | Any file |
| terminalProgressBarEnabled | Hide the terminal progress bar in terminals that support it | Any file |
| terminalTitleFromRename | Stop /rename and --name from changing the terminal tab title | Any file |
| theme | Pick the interface color theme, built-in or custom | Any file |
| timeFormat | Show the times in the interface on a 12-hour or 24-hour clock, in UTC, or with a strftime pattern | Any file |
| timeZone | Show the times in the interface in a time zone other than your system's | Any file |
| tui | Choose the fullscreen or classic terminal renderer | Any file |
| ultracode | Have Claude plan a workflow for each substantive task without being asked | Any file |
| useAutoModeDuringPlan | Let the auto mode classifier review shell commands in plan mode; set false to get prompts instead | User, local, or managed |
| verbose | Show full tool output instead of truncated summaries; viewMode takes precedence when both are set | Any file |
| viewMode | Start every session in default, verbose, or focus view | Any file |
| vimInsertModeRemaps | Map a two-key INSERT-mode sequence such as jj to Escape | User or managed |
| voice | Turn on voice dictation and pick hold or tap mode | Any file |
| voiceEnabled | Turn on voice dictation with the older single-key form | Any file |
| wheelScrollAccelerationEnabled | Turn off mouse-wheel acceleration in fullscreen rendering | Any file |
| workflowKeywordTriggerEnabled | Let the word ultracode in a prompt start a workflow; set false to type it without starting one | Any file |
| workflowSizeGuideline | Set the agent count Claude aims for in dynamic workflows | Any file |
| worktree | Configure how Claude Code creates git worktrees | Any file |
| wslInheritsWindowsSettings | Have WSL read managed settings from the Windows policy chain | Managed |
FAQ
What does a Claude Code settings.json example look like?
The smallest useful one is the example under "A Claude Code settings.json example" above: a $schema line, then a permissions object with allow and deny lists. Anthropic's example settings files page has three fuller ones, for a developer, a team and an organization. Load any of them into the validator above.
Where is settings.json in Claude Code?
There are three files you edit: ~/.claude/settings.json for you in every project, .claude/settings.json in a project for the whole team, and .claude/settings.local.json for you in one project. Installing Claude Code creates none of them (Find or create your settings files). On Windows, ~/.claude is %USERPROFILE%\.claude.
Is there a JSON schema for Claude Code settings?
Yes. Add "$schema": "https://json.schemastore.org/claude-code-settings.json" as the first key to get autocomplete in VS Code, Cursor and other editors. The docs say "The schema can lag behind the newest CLI releases, so a validation warning on a recently documented key doesn't mean your configuration is invalid" (Edit a settings file). This validator reads the settings reference instead of the schema, and dates its copy.
How do I write permissions in settings.json?
Put rules in permissions.allow, ask or deny. Each rule is Tool or Tool(specifier), such as Bash(npm run *), Read(./.env) or WebFetch(domain:example.com). Claude Code checks deny first, then ask, then allow, and the first match wins (Permission rule syntax).
How do I set environment variables in settings.json?
Use the env key, an object of names to string values: "env": { "DISABLE_AUTO_COMPACT": "1" }. Quote numbers and booleans. A value there overwrites the same variable exported in your shell, and project and local files cannot set some variables (env).
Why does Claude Code ignore a key I set?
The usual causes: the key is misspelled, it belongs in ~/.claude.json (global config keys), it only works in managed settings, or a higher-priority file sets it too. Pick the file in the validator to check scope, then run /status and claude doctor as the docs suggest (Troubleshoot a setting that doesn't apply).
Can settings.json have comments?
No. The docs say settings files are strict JSON, and "a // comment or a trailing comma is a syntax error" (Edit a settings file). The validator names the line and column of the first one it finds.
Is my settings.json uploaded anywhere?
No. The checks run in JavaScript in your browser. There is no backend, no API key and no model call. A dropped file is read locally with the browser's File API. Still, keep real secrets out of env in a file you commit.
Related
- Claude Code hooks builder: make a hooks block from the docs' events
- CLAUDE.md linter: check your file against Claude Code best practices
- SKILL.md validator: check a Claude skill against the spec
- Claude Code with Claude Fable 5.2: setup and cost
- All free Claude Code tools
- Browse Claude skills, agents and hooks
Sources
All read on 2026-11-12. The hash is the sha256 of the page's Markdown export (the page URL with .md added).
- Settings files and precedence (Claude Code docs): https://code.claude.com/docs/en/settings
sha256 e180e905de3bbf69dd932eb37a2ea9af8d7e937ade9cc98fdcd493df85ca18cc - All settings (settings reference) (Claude Code docs): https://code.claude.com/docs/en/settings-reference
sha256 164320461acfc2ab93d6f7dfddb859fe3d36aef77ac9aeca28fe744d523c65fd - Example settings files (Claude Code docs): https://code.claude.com/docs/en/settings-example
sha256 1a47ec2d37d6c36cfed03ca9c7c7760faef657ed88954fa9978f1ed4ed23ab7e - Configure permissions (Claude Code docs): https://code.claude.com/docs/en/permissions
sha256 86be6c5404b154e7dec0dc5aca2d145eb53e01c75d1cb9843fdce3da2f4a37f8 - Hooks reference (Claude Code docs): https://code.claude.com/docs/en/hooks
sha256 ebb8e6a8edbdf997f9637389d31cd0d8c0f23eb4e7053f6c6bbad490cea8dea3 - Model configuration (Claude Code docs): https://code.claude.com/docs/en/model-config
sha256 37edc7e03c00d7511a1b2d85d9208961223364166b10368e37e28118885f5bd4 - Tools reference (Claude Code docs): https://code.claude.com/docs/en/tools-reference
sha256 03aefabd00df3af010667bfef9178529b8f64fe89e9beac03ad40c3c7362f4c8 - RFC 8259, The JSON Data Interchange Format, section 4: https://www.rfc-editor.org/rfc/rfc8259#section-4