Where is the Claude Code settings file?

Your own settings are in ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json). A project's shared settings are in .claude/settings.json inside the project, and your personal settings for that project in .claude/settings.local.json. Installing Claude Code creates none of them; they appear when you change a setting or create them yourself.

Which Claude Code settings file wins?

Managed settings from your organization first, then --settings on the command line, then .claude/settings.local.json, then the project's .claude/settings.json, then your ~/.claude/settings.json. List settings such as permission rules are combined from every file instead of replaced.

Should I commit .claude/settings.json?

Yes, if the team should share it - permission rules, hooks, plugins and the environment variables the project needs. Keep personal choices in .claude/settings.local.json, which Claude Code keeps out of Git when it creates the file.

Do I need to restart Claude Code after changing settings?

Usually not. Claude Code watches its settings files and applies most changes, including permissions and hooks, to the running session. A few, such as model, are read only at the start; use /model to switch in a session.

How do I check which settings Claude Code loaded?

Run /status and look at the Setting sources line, which lists every file read for this session. claude doctor lists entries that were rejected and why.

Claude Code settings.json: where it lives and the settings that matter

Claude Code reads settings from JSON files at 3 levels you control - ~/.claude/settings.json for you in every project, .claude/settings.json for the team in one project, and .claude/settings.local.json for you in one project - plus settings your organization may manage. The more specific file wins, except that lists such as permission rules are added together.

Control

Take this page into your AI

ChatGPT Claude

Claude Code's settings are JSON files. They decide which model a session starts with, what Claude may do without asking, which hooks and plugins run, and how the screen looks. You can change most of them from /config without opening a file, but knowing where they live tells you why a setting does or does not apply.

The 3 files you control

File	Applies to	Use it for
`~/.claude/settings.json`	You, in every project	Your model, theme, editor keys and your own permission rules
`.claude/settings.json`	Everyone in this project, once committed	Team permission rules, hooks, plugins and the project's environment variables
`.claude/settings.local.json`	You, in this project only	Your own exceptions to the team file, and trying a change before sharing it

An organization can also deploy managed settings to its developers' machines. Nothing in your files overrides those.

Installing Claude Code creates none of these files. ~/.claude/settings.json appears when you first change something in /config, and .claude/settings.local.json when you first choose "Yes, and don't ask again" on a permission prompt. Claude Code keeps that local file out of your Git commits; if you create it by hand, add it to .gitignore yourself.

There is a 4th file, ~/.claude.json, that Claude Code writes for itself: your sign-in, your MCP servers and which folders you trusted. You rarely need to edit it.

A starting file

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  },
  "attribution": { "commit": "", "pr": "" },
  "cleanupPeriodDays": 60
}

The $schema line gives you autocomplete and checking in VS Code, Cursor and other editors that read JSON schemas. The files are strict JSON: a comment or a trailing comma is an error, and Claude Code tells you about it at the next start.

Which file wins

When the same setting is in more than one place, the higher one in this list is used:

Managed settings from your organization
--settings on the command line, for that session only
.claude/settings.local.json
.claude/settings.json
~/.claude/settings.json

So a team file that sets "model": "sonnet" beats your own "opus" in that project, and your .claude/settings.local.json beats the team file.

Lists work differently. Permission rules, for example, are added together from every file, so the team's deny rules and your own allow rules all apply. Some settings also have a flag or an environment variable that overrides any file: --model for model, for one.

A few settings are refused from a project file for safety. A repository cannot make your sessions start in auto or bypass mode, and its allow rules wait until you trust the folder. Permissions has the detail.

Changing a setting

/config opens a menu of the everyday options: theme, editor mode, verbose output and more. /config verbose=true sets one directly.
Edit the file for anything the menu does not show, such as hooks or permission rules.
For one session, pass --settings '{"model": "opus"}', or the setting's own flag such as --model opus. Nothing is saved.

Most changes take effect at once in the running session, including permission rules and hooks. A few are read only at the start: model is one, which is why /model exists.

If a setting seems to be ignored, run /status. Its Setting sources line lists every file read for this session. claude doctor lists any entries it rejected and why.

Settings worth knowing

The full reference has over 200 settings, many for administrators. These are the ones you are likely to want. Each example is the line to add. A setting with a dot in its name, such as permissions.allow, goes inside that block: "allow" inside "permissions".

Find a setting

Show

57 settings

modelModel
The model every new session starts with, as a name such as opus or sonnet or a full model id. /model still switches during a session.
"model": "opus"
effortLevelModel
How hard the model thinks by default, from low to xhigh. Lower is faster and cheaper on simple work. /effort saves a level for the model you are using.
"effortLevel": "high"
fallbackModelModel
Models to try, in order, when the main one is overloaded or unavailable, for the rest of that turn.
"fallbackModel": ["sonnet"]
languageModel
The language Claude answers in. Any language name works, since it is passed to Claude as an instruction.
"language": "German"
outputStyleModel
An output style by name, which changes Claude's tone and format, such as the built-in Explanatory or Learning styles or one you wrote.
"outputStyle": "Explanatory"
alwaysThinkingEnabledModel
Set to false to turn extended thinking off. Thinking is on by default, and models that always think ignore it.
"alwaysThinkingEnabled": false
showThinkingSummariesModel
Shows summaries of Claude's thinking when you expand it with Ctrl+O, instead of a collapsed line.
"showThinkingSummaries": true
fastModeModel
Turns fast mode on where it is available, for quicker answers at a higher price. /fast writes it for you.
"fastMode": true
promptCacheTtlModel
How long the prompt cache keeps the conversation, 5 minutes or 1 hour. The longer lifetime survives breaks, but each cache write costs more.
"promptCacheTtl": "1h"
agentModel
Runs every session as one of your subagents, with its instructions, tools and model.
"agent": "reviewer"
permissions.allowPermissions
Tool uses that run without asking, such as a command or a web domain.
"allow": ["Bash(npm run *)", "Bash(git diff *)"]
permissions.askPermissions
Tool uses that always ask first, even in modes that would not.
"ask": ["Bash(git push *)"]
permissions.denyPermissions
Tool uses that are refused in every mode, such as reading files that hold secrets. Deny beats allow wherever each is set.
"deny": ["Read(./.env)", "Read(./secrets/**)"]
permissions.defaultModePermissions
The permission mode sessions start in, such as plan or acceptEdits. A project file cannot start sessions in auto or bypassPermissions.
"defaultMode": "plan"
permissions.additionalDirectoriesPermissions
Folders outside the project that Claude may work in, like --add-dir every time.
"additionalDirectories": ["../shared-lib"]
permissions.blockReadsOutsideWorkingDirectoriesPermissions
Makes the file tools refuse to read outside your working folders in every mode, bypass included.
"blockReadsOutsideWorkingDirectories": true
permissions.disableBypassPermissionsModePermissions
Set to "disable" so no one can switch to bypassPermissions. Most useful in managed settings.
"disableBypassPermissionsMode": "disable"
disableAutoModePermissions
Takes auto mode out of the Shift+Tab cycle, so sessions that would start in it start in Manual.
"disableAutoMode": "disable"
autoModePermissions
Your own rules for the auto mode classifier, such as the repositories and domains your company trusts, so it stops blocking routine work.
sandbox.enabledSandbox
Runs Bash commands inside the operating system sandbox. /sandbox writes it for the current project.
"sandbox": { "enabled": true }
sandbox.network.allowedDomainsSandbox
Domains sandboxed commands may reach without asking. *.example.com covers subdomains.
"allowedDomains": ["registry.npmjs.org", "*.github.com"]
sandbox.filesystem.allowWriteSandbox
Extra folders sandboxed commands may write to, beyond the project and the temp folder, for tools such as kubectl.
"allowWrite": ["~/.kube"]
sandbox.filesystem.denyReadSandbox
Paths sandboxed commands may not read, such as credential files.
"denyRead": ["~/.aws/credentials"]
sandbox.excludedCommandsSandbox
Commands that run outside the sandbox because they do not work inside it, written like Bash permission rules.
"excludedCommands": ["docker *"]
autoMemoryEnabledMemory
Set to false to stop Claude reading and writing its own notes. /memory has the same switch.
"autoMemoryEnabled": false
autoMemoryDirectoryMemory
A folder of your choice for auto memory, instead of the one under ~/.claude/projects/.
"autoMemoryDirectory": "~/notes/claude-memory"
claudeMdExcludesMemory
CLAUDE.md files to skip, by path or pattern, such as other teams' files in a monorepo.
"claudeMdExcludes": ["**/other-team/CLAUDE.md"]
autoCompactEnabledMemory
Set to false to stop Claude Code compacting the conversation on its own when the context window fills.
"autoCompactEnabled": false
autoCompactWindowMemory
How many tokens the conversation may reach before automatic compaction, from 100,000 up to the model's context window.
"autoCompactWindow": 400000
fileCheckpointingEnabledMemory
The snapshots that let /rewind restore files. Set to false and /rewind can only rewind the conversation.
"fileCheckpointingEnabled": true
plansDirectoryMemory
Where plan mode saves its plan files, relative to the project. By default they go to ~/.claude/plans.
"plansDirectory": "./plans"
cleanupPeriodDaysMemory
How many days sessions are kept before they are deleted. The default is 30.
"cleanupPeriodDays": 90
envMemory
Environment variables set for every session and every command it runs.
"env": { "NODE_ENV": "development" }
hooksExtend
Your own commands that run at fixed points, such as before a tool call or when a session starts. See the hooks page.
disableAllHooksExtend
Turns off every hook and any custom status line at once, without deleting them.
"disableAllHooks": true
enabledPluginsExtend
Plugins switched on or off, by plugin@marketplace. /plugin writes it for you.
"enabledPlugins": { "code-review@claude-plugins-official": true }
extraKnownMarketplacesExtend
Plugin marketplaces everyone who opens the repository gets, without adding them by hand.
enabledMcpjsonServersExtend
Servers from the project's .mcp.json that connect without asking. Approving one in the dialog writes it.
"enabledMcpjsonServers": ["github"]
disabledMcpjsonServersExtend
Servers from the project's .mcp.json that never connect and are never offered.
"disabledMcpjsonServers": ["filesystem"]
enableAllProjectMcpServersExtend
Connects every server in a project's .mcp.json without asking. Only for repositories you trust.
"enableAllProjectMcpServers": true
apiKeyHelperExtend
A script that prints the key Claude Code sends with each request, for short-lived keys from a vault.
"apiKeyHelper": "~/bin/get-claude-key.sh"
statusLineExtend
Your own command that draws a line under the prompt, such as the model, the cost so far or the Git branch.
"statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
attributionGit
The credit line Claude Code adds to commits and pull requests. Set commit or pr to your own text, or the whole key to false to leave it out.
"attribution": { "commit": "", "pr": "" }
includeGitInstructionsGit
Set to false to drop Claude Code's own instructions for writing commits and pull requests, and the Git status it reads at the start, when you use your own.
"includeGitInstructions": false
worktree.baseRefGit
What new worktrees branch from - fresh for the remote's default branch, head for where you are now.
"worktree": { "baseRef": "head" }
worktree.symlinkDirectoriesGit
Large folders, such as node_modules, linked into each new worktree instead of copied.
"worktree": { "symlinkDirectories": ["node_modules"] }
worktree.sparsePathsGit
Checks out only these folders in each worktree, which is faster in a large monorepo.
"worktree": { "sparsePaths": ["apps/web", "packages/ui"] }
themeInterface
The colour theme - auto to follow the terminal, dark, light, or a colour-blind friendly version of either.
"theme": "dark-daltonized"
editorModeInterface
Set to vim for vim keys in the prompt, with normal, insert and visual modes.
"editorMode": "vim"
tuiInterface
The screen renderer - fullscreen for the flicker-free view, or default for the classic one. /tui sets it.
"tui": "fullscreen"
viewModeInterface
How much the transcript shows - default, verbose for every tool's full output, or focus for only your prompt and the answer.
"viewMode": "verbose"
verboseInterface
Shows every tool call's full input and output as it happens, handy when debugging a hook or an MCP server.
"verbose": true
respectGitignoreInterface
Whether the @ file picker leaves out files your .gitignore ignores.
"respectGitignore": false
spinnerTipsEnabledInterface
Set to false to hide the tips shown while Claude works.
"spinnerTipsEnabled": false
prefersReducedMotionInterface
Calms or turns off the spinner and other animations.
"prefersReducedMotion": true
voiceInterface
Voice dictation, held or tapped. /voice writes it for you.
"voice": { "enabled": true, "mode": "tap" }
autoUpdatesChannelInterface
Which releases updates follow - latest, or stable, which is usually about a week old and skips releases with major problems.
"autoUpdatesChannel": "stable"

Questions

Where is the Claude Code settings file?: Your own settings are in ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json). A project's shared settings are in .claude/settings.json inside the project, and your personal settings for that project in .claude/settings.local.json. Installing Claude Code creates none of them; they appear when you change a setting or create them yourself.
Which Claude Code settings file wins?: Managed settings from your organization first, then --settings on the command line, then .claude/settings.local.json, then the project's .claude/settings.json, then your ~/.claude/settings.json. List settings such as permission rules are combined from every file instead of replaced.
Should I commit .claude/settings.json?: Yes, if the team should share it - permission rules, hooks, plugins and the environment variables the project needs. Keep personal choices in .claude/settings.local.json, which Claude Code keeps out of Git when it creates the file.
Do I need to restart Claude Code after changing settings?: Usually not. Claude Code watches its settings files and applies most changes, including permissions and hooks, to the running session. A few, such as model, are read only at the start; use /model to switch in a session.
How do I check which settings Claude Code loaded?: Run /status and look at the Setting sources line, which lists every file read for this session. claude doctor lists entries that were rejected and why.

Sources