Claude Code settings scopes and managed policy delivery for teams

1.Four settings scopes, and the one a team shares

Claude Code reads its configuration from several scopes at the same time. Most of the work of setting it up for a team is deciding which scope each key goes in. The settings documentation describes four. User settings in ~/.claude/settings.json follow one developer into every project on their machine. Shared project settings in .claude/settings.json apply to everyone working in that folder, and this is where team permissions, hooks, plugins and the project's environment variables belong. Project local settings in .claude/settings.local.json hold one developer's overrides for one project. Managed settings come from the organization, and developers don't create or edit them.

The shared project file only becomes team configuration once you commit it. Until then it's an ordinary file on one disk, and neither teammates' clones nor cloud sessions see it. The local file works the other way round. The first time Claude Code writes it inside a git repository, it adds **/.claude/settings.local.json to your global git excludes so it stays out of commits. If you create the file by hand, you have to gitignore it yourself. Claude Code also writes to this file without being asked: choosing "Yes, and don't ask again" on a Bash prompt saves an allow rule there.

When the same key is set in more than one place, precedence runs from managed settings, then command-line arguments, then project local, then shared project, then user. JSON passed with --settings sits above the user, project and local files and below managed settings, and a key passed that way can't override the same managed key.

Sources1

2.Delivering managed policy to every machine

Managed policy can reach developers in four ways. Server-managed settings are set in the claude.ai admin console, or on a self-hosted Claude apps gateway. They give a claude.ai organization one place to change policy without touching individual machines. MDM or OS-level policy is a macOS configuration profile in the com.anthropic.claudecode domain, or a Windows registry value named Settings under HKLM\SOFTWARE\Policies\ClaudeCode, pushed through Jamf, Intune, Group Policy or a similar tool. File-based policy is a managed-settings.json file, an optional managed-settings.d/ directory, and managed-mcp.json, all in a system directory. It suits machines without MDM, Linux hosts, and images you build yourself. HKCU registry is the fallback when you can't write the machine-level HKLM key. Because developers can write to it, it is not an admin source.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

The file goes in /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows. Claude Code no longer reads the legacy C:\ProgramData path.

Coverage depends on where a session runs. On a developer's machine, the terminal, the VS Code and JetBrains extensions, the desktop app's Code tab and Agent SDK sessions all read these sources. The SDK loads managed settings even when settingSources leaves out the user, project and local files. A session in an Anthropic-hosted environment has no device to read, so its policy has to come from server-managed settings. Server-managed settings have a limit of their own: Claude Code fetches them only when the session authenticates to Anthropic's API directly. On other providers, or when ANTHROPIC_BASE_URL points somewhere else, it moves straight to the next source. Teams on a third-party cloud therefore need MDM or file-based delivery.

Most changes reach a session that is already running, on the schedule shown in the table, with no restart. One exception: a server-managed change to a setting that needs approval, such as a hook or an env variable, waits until the developer accepts a dialog in an interactive session.

Sources2

3.When several managed sources exist: first-wins, merge and /status

Managed sources are ranked. Remote settings (server-managed or from a gateway) come first, then MDM/OS-level policy, then the managed settings files, and the HKCU registry comes last. The managedSourcesBehavior key controls what happens when more than one is present. Under the default, "first-wins", Claude Code applies the highest-ranked source that delivers at least one policy key and skips the rest, without any warning. Under "merge" (Claude Code v2.1.242 or later), it applies every admin source: on most keys the higher-ranked value wins, lists are unioned, and locks take the strictest value.

The file tier always combines its own pieces. managed-settings.d/*.json and managed-settings.json merge together: for a single value, the later file replaces the earlier one; lists such as permissions.deny combine with duplicates removed; and nested blocks such as env merge key by key.

A few keys are read from every admin source, even under first-wins. A true for allowManagedMcpServersOnly in any admin source turns the MCP allowlist lock on. Entries in deniedMcpServers apply from any source. For maxEffortLevel, the lowest cap in any admin source applies. The env block merges per variable across admin sources.

To confirm which source actually took effect, run /status. It names the source Claude Code used and the ones it skipped. That matters because a skipped source produces no warning anywhere else.

Sources2

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Putting .claude/settings.json in the project folder shares it with the whole team.Why is that wrong?

   The shared project file reaches teammates and cloud sessions only after it is committed to version control. Until then it exists on one disk only.

   Covered in Four settings scopes, and the one a team shares

2. 2.A managed-settings.json or MDM profile on every laptop also governs the developers' cloud sessions.Why is that wrong?

   Anthropic-hosted sessions have no device to read. Their policy has to come from server-managed settings.

   Covered in Delivering managed policy to every machine

3. 3.When an organization delivers policy through several managed sources, Claude Code merges them all by default.Why is that wrong?

   The default is first-wins: only the highest-ranked source with a policy key applies, apart from a short list of keys read from every admin source. Merging requires setting managedSourcesBehavior to "merge".

   Covered in When several managed sources exist: first-wins, merge and /status