# 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.

- Page: https://tecyfy.com/coding-agents/claude-code/settings
- Guide: Claude Code (https://tecyfy.com/coding-agents/claude-code), from Anthropic's documentation (https://code.claude.com/docs/en/overview)

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

```json
{
  "$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:

1. Managed settings from your organization
2. `--settings` on the command line, for that session only
3. `.claude/settings.local.json`
4. `.claude/settings.json`
5. `~/.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](/coding-agents/claude-code/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"`.

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

- [Settings files and precedence](https://code.claude.com/docs/en/settings)
- [Settings reference](https://code.claude.com/docs/en/settings-reference)