Text of code.claude.com › docs › en › settings as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Settings files and precedence - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Settings are the JSON keys that change how Claude Code behaves: which model it starts with, what it can run without asking, which files it can’t read, how it looks in your terminal, and what your organization enforces.

To look up a specific key, go to All settings , which lists every key with the file you set it in, its default, and an example. Claude Code reads settings from JSON settings files such as ~/.claude/settings.json . It looks for them in a few locations, and the file it reads a setting from decides who the setting applies to . This page covers those files: which one to put a setting in, how to change a setting and confirm it applied, and which value Claude Code uses when the same key is set in more than one file.

Configure permissions covers what Claude Code can run without asking and how to write allow , ask , and deny rules. This page covers Claude Code running on your machine: the terminal, the VS Code and JetBrains extensions, and the desktop app , which all read the same settings files. A cloud session runs on a different machine and reads only some of them; see Settings in cloud sessions . Settings files and who they affect Claude Code reads settings from four files, and an organization can also deliver managed settings from the claude.ai console.

Each source has a scope: the set of people and projects a setting saved in it applies to, whether that’s only you, everyone in a project, or everyone in your organization. Scope File Who it affects Use it for User ~/.claude/settings.json You, in every project on this machine Personal preferences: theme, editor mode, default model, your own permission rules Shared project .claude/settings.json Everyone working in the folder that contains it.

In a git repository, commit it so teammates get it Team permissions, hooks, plugins, and the environment variables the project needs Project local .claude/settings.local.json You, in this one project only. Claude Code keeps it out of git when it creates the file; if you create it by hand, add it to .gitignore yourself Personal overrides for one project, and testing before you share Managed managed-settings.json and other managed sources Everyone your organization deploys it to; Settings precedence says what can override it Security policy and compliance requirements In the File column, ~/.claude is the .claude folder in your home directory, and a bare .claude is the .claude folder inside your project.

Compare the scope of each settings file Suppose you have three projects on your machine, website/ , api/ , and acme-app/ , a teammate has their own clone of acme-app/ , and you start a cloud session on acme-app/ . The graphic below shows which of those folders a setting applies in when you start Claude Code from them. Click a settings file to see the folders it reaches. ~/.claude/settings.json : every project on your machine, and nothing on your teammate’s or in the cloud session acme-app/.claude/settings.json : your acme-app/ .

It reaches your teammate’s clone and the cloud session only if you commit the file to version control; until you do, it’s a file on your disk like any other and nobody else has it acme-app/.claude/settings.local.json : your acme-app/ only. Claude Code adds it to your global git excludes the first time it writes the file, so it stays out of your commits; if you create the file by hand, add it to .gitignore yourself Managed settings , whether a managed-settings.json file, an MDM policy, or server-managed settings from the claude.ai console: every project on every machine your organization deploys it to, or that you sign in to with your organization account.

Only server-managed settings reach the cloud session Find or create your settings files Installing Claude Code doesn’t create any settings file. If your machine or project already has one, it came from one of these sources: Managed : your organization deploys it. You don’t create or edit it. Shared project : a project that already uses Claude Code may have one committed. If not, create it at .claude/settings.json in the project folder.

User and Project local : create them yourself, or let Claude Code create them. It writes ~/.claude/settings.json the first time you change an option in the /config menu that it stores in user settings, such as the theme, and .claude/settings.local.json the first time you give a standing approval on a permission prompt, such as “Yes, and don’t ask again” for a Bash command. A few /config options, including Show tips , save to .claude/settings.local.json instead of the user file.

On Windows, ~/.claude means %USERPROFILE%\.claude . To keep the home-directory files somewhere else, set CLAUDE_CONFIG_DIR ; Claude Code then stores your settings, session history, and plugins there instead. Claude Code also keeps a fifth file, ~/.claude.json , that it writes for itself; you don’t need to edit it. It holds your account details, MCP server configurations, per-project state such as trust decisions, and the global config keys that /config writes for you.

Share settings with your team Commit .claude/settings.json so everyone who clones the repository gets the same permissions, hooks, and plugin settings. Each teammate can still override it for themselves in their own .claude/settings.local.json , so personal exceptions don’t need a commit. For a complete team file, see a team’s shared settings . Some of what you commit waits until each teammate trusts the folder , and a few keys never take effect from a repository file; Troubleshoot a setting that doesn’t apply covers both.

Keep personal settings out of a repository To change a setting for yourself in one project without changing it for your teammates, save it in .claude/settings.local.json inside the project. Claude Code applies that file over the committed .claude/settings.json , so if your team’s file sets "model": "claude-sonnet-5" and you want Opus, put "model": "claude-opus-5-5" in your local file and only your sessions change. Claude Code also writes to this file, keeps it out of your commits, and applies its allow rules without the trust step: Claude Code writes it too.

When Claude asks permission to run a Bash command and you choose “Yes, and don’t ask again”, Claude Code saves that permission approval here as an allow rule. You don’t need to gitignore it yourself, unless you created it by hand. The first time Claude Code writes the file in a git repository that doesn’t already ignore it, it adds **/.claude/settings.local.json to your global git excludes file, so the file stays out of your commits in every repository.

That file is core.excludesFile when your global git config sets it to an absolute or ~ -prefixed path; otherwise it’s $XDG_CONFIG_HOME/git/ignore , or ~/.config/git/ignore when XDG_CONFIG_HOME is unset. If you created the file by hand and Claude Code hasn’t written to it yet, add it to .gitignore yourself. Its allow rules don’t wait for trust while the file stays untracked. Because the file is yours and not the repository’s, Claude Code applies its allow rules without the workspace trust step it requires for the committed file.

If the file is tracked by git, the trust step applies to it too; see When your local settings file needs trust . Where Claude Code keeps the local file in a git repository When Claude asks permission to run a Bash command and you choose “Yes, and don’t ask again”, Claude Code saves that approval as an allow rule in .claude/settings.local.json . If you start Claude Code in a subdirectory of a git repository, it reads and writes that file at the repository root and applies the approval across the whole repository.

In a worktree , it uses the file at the main checkout’s root. T

The rest of this page is on the live site.