Where do Claude Code's settings files live, and which one does a team commit versus keep personal?
answer
- four files, four audiences
- home folder versus project folder
- one project file stays out of git
- the organization's layer you never edit
- ~/.claude.json holds state, not settings
basics
~10 sClaude Code reads ~/.claude/settings.json (you, every project), .claude/settings.json (the team, committed), .claude/settings.local.json (you, one project, kept out of git) and managed settings an organization deploys.
solid answer
~40 sThere are four settings files. `~/.claude/settings.json` holds personal preferences for every project on the machine. `.claude/settings.json` is the shared project file the team commits, so every clone gets the same permissions, hooks, plugins and `env`. `.claude/settings.local.json` is your personal override for one project; Claude Code saves "don't ask again" approvals there and adds it to your global git excludes the first time it writes it. Managed settings come from the organization and you don't edit them. Separately, `~/.claude.json` is Claude Code's own state file — sign-in, per-project trust, personal MCP servers and a few global config keys — and it ignores `permissions`, `hooks` or `env` placed there.
go deeper
Recall the four paths and who each reaches: you everywhere, the team, you in one project, the organization. Know that the local file stays out of git.
Explain how Claude Code itself writes the local file, why it ends up in global git excludes, and why ~/.claude.json is a separate state file rather than a fifth settings layer.
Show you place each key deliberately: team policy committed, personal exceptions local, preferences in the user file, and you know which files a cloud session never sees.
Discuss what a team should commit versus leave personal, and when a rule belongs in managed settings instead because a committed file can be overridden locally.
## The four settings files Claude Code reads its configuration from **settings files**: strict JSON documents whose keys turn behaviour on or off, hold permission rules, declare hooks and set environment variables. Installing Claude Code creates none of them. There are four, and each one has a **scope** — the set of people and projects a value saved in it reaches. | Scope | File | Who it affects | Typical content | | :- | :- | :- | :- | | User | `~/.claude/settings.json` | You, in every project on this machine | Theme, editor mode, default model, your own rules | | Shared project | `.claude/settings.json` | Everyone working in the project once it is committed | Team permissions, hooks, plugins, the `env` the project needs | | Project local | `.claude/settings.local.json` | You, in this one project only | Personal overrides, trying a value before sharing it | | Managed | `managed-settings.json`, MDM policy or server-managed settings | Everyone the organization deploys it to | Security and compliance policy | `~/.claude` is the `.claude` folder in your home directory; a bare `.claude` is the folder inside the project. On Windows the home folder is `%USERPROFILE%\.claude`, and the `CLAUDE_CONFIG_DIR` environment variable moves the home-directory files elsewhere. ## The shared file and the local file The **shared project file**, `.claude/settings.json`, is just a file on your disk until you commit it. Once it is in version control, every clone gets it — that is how a team standardises permissions, hooks and plugins without each developer copying them by hand. Some of what it carries, such as `permissions.allow` rules and most `env` values, waits until each developer accepts the workspace trust dialog for the folder. The **project local file**, `.claude/settings.local.json`, is the personal layer for one project. It sits above the shared file, so a developer can override a team value for themselves without a commit. Claude Code writes to it too: - choosing "Yes, and don't ask again" on a permission prompt saves an `allow` rule there; - a few `/config` options, such as **Show tips**, save there instead of the user file; - 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 it stays out of commits in every repository. If you create the file by hand before Claude Code has written to it, add it to `.gitignore` yourself. ## Managed settings **Managed settings** are deployed by an organization: a `managed-settings.json` file in a system directory, an MDM or OS-level policy, or server-managed settings fetched from the claude.ai admin console. A developer doesn't create or edit them, and nothing in the developer's own files overrides them apart from a short list of security-sensitive exceptions. How they are delivered and which keys only they can set are the managed-policy material; for this question the point is that they form the top layer. ## The fifth file: ~/.claude.json Claude Code also keeps `~/.claude.json`, a file it writes for itself. It is **state, not settings**: 1. your sign-in session; 2. per-project state such as trust decisions; 3. MCP servers added at user or local scope; 4. a handful of **global config keys**, such as `autoConnectIde`, which Claude Code reads only from this file. The reverse also holds: `permissions`, `hooks` and `env` written into `~/.claude.json` are ignored, because they belong in `~/.claude/settings.json`. Mixing the two files up is one of the most common reasons a "global" rule never applies. ## How values get written You can edit any of the files by hand — add a `$schema` line pointing at `https://json.schemastore.org/claude-code-settings.json` to get editor autocomplete and validation — or let Claude Code write them: - most `/config` options save to `~/.claude/settings.json`; - the global config options save to `~/.claude.json`; - `/model` saves your pick as the default for new sessions in the user file. Because the files are strict JSON, a `//` comment or a trailing comma is a syntax error that Claude Code reports at the next start. ## Common placement mistakes - Putting a personal preference in the committed file, which changes it for the whole team. - Expecting a teammate to receive values from your `.claude/settings.local.json` — it never leaves your machine. - Expecting user or local settings to reach a cloud session, which reads only the committed project file and server-managed settings. - Editing `~/.claude.json` to add permission rules or hooks.
- Why might .claude/settings.local.json appear in a project even though nobody created it?Claude Code writes it. Answering "Yes, and don't ask again" on a permission prompt saves an `allow` rule there, and a few `/config` options such as **Show tips** save there too. The first time it writes the file in a git repository that doesn't already ignore it, Claude Code adds `**/.claude/settings.local.json` to your global git excludes file.
- You added permissions and hooks to ~/.claude.json and none of them apply. Why?`~/.claude.json` is Claude Code's state file: sign-in, per-project trust, personal MCP servers and global config keys such as `autoConnectIde`. It doesn't read `permissions`, `hooks` or `env` from it. Those belong in `~/.claude/settings.json`, a different file in a different place.
- Which of these files does a Claude Code cloud session read?A cloud session runs on a fresh clone, so it reads the committed `.claude/settings.json` (fully in a single-repository session) and the organization's server-managed settings. Your `~/.claude/settings.json`, your `.claude/settings.local.json` and a device-level `managed-settings.json` stay on your machine and never reach it.
- settings.local.json should be committed so teammates share each other's overrides
- Permission rules and hooks can live in ~/.claude.json next to MCP servers
- Installing Claude Code creates a default settings.json in every project
- A developer can edit managed settings to opt out of an organization policy
- ~/.claude/settings.json only applies to the project it was edited from