OmniscioGuidesClaude Code team settings
Claude Code team settings: one setup for the whole team
Claude Code reads its instructions and settings from the project as well as from your home folder, so a team can get one behaviour out of the box simply by committing the right files.
This page covers which files to commit and which to keep out, what a teammate actually receives, the trust dialog that decides whether your rules take effect, and where a company-wide policy has to live instead.
Last checked against Anthropic's Claude Code documentation on November 18, 2026. By the Omniscio team. Updated .
What to commit, and what never to
Anthropic's rule of thumb is short: commit project files to share them with your team, and treat ~/.claude as personal configuration that applies across all your projects. The directory guide carries a commit column for every file, and this is it.
- Commit:
CLAUDE.md,.claude/rules/*.md,.claude/settings.json,.mcp.json,.worktreeinclude, and the contents of.claude/skills/,commands/,output-styles/,agents/,workflows/andagent-memory/. - Never commit:
.claude/settings.local.json, which is a person's own overrides and is gitignored when Claude Code writes to it. - Live in your home folder, never the repo:
~/.claude.json, auto memory, keybindings and themes.
The two files people mix up are settings.json and settings.local.json. Same format, opposite audience: the first is the team's agreement, the second is one person's exception to it.
Sources: the open of Explore the .claude directory and its commit table, read November 18, 2026.
What a teammate gets after a clone
Each committed file does a different job on their machine, and it helps to say which one you are relying on when you add it.
- CLAUDE.md and rules are guidance Claude reads every session. Anthropic is explicit that these are instructions Claude follows, not controls that cannot be skipped.
- .claude/settings.json holds permissions, hooks and environment values. These are enforced whether Claude agrees or not, which is why the deny rules live here.
- .mcp.json holds the project-scoped MCP servers the whole team uses. Personal servers belong in
~/.claude.json. - Skills, commands, subagents and output styles give everyone the same slash commands and delegated behaviours.
One thing does not travel: auto memory is machine-local, so the notes Claude writes for itself on your computer are not shared with a colleague. What you want shared belongs in CLAUDE.md. The CLAUDE.md guide covers what earns a place there.
Sources: Explore the .claude directory and the auto-memory limits in How Claude remembers your project, read November 18, 2026.
The trust dialog is the gate
This is the part that makes a committed setup feel broken. A repository's .claude/settings.json does not take full effect the moment it is cloned.
Anthropic says deny and ask rules apply right away, while allow rules, permissions.additionalDirectories, extraKnownMarketplaces and most env values wait until each teammate trusts the folder. Hooks wait for the same trust.
So a teammate who has just cloned the repository may still see prompts your allow rules were meant to remove, and their first session shows a trust prompt listing what the folder would activate. That is the design: the repository can restrict you immediately, but it cannot grant itself permissions without you agreeing.
Sources: the trust paragraph in Anthropic's settings page and "Choose who a rule applies to" in best practices, read November 18, 2026.
Who wins when two files disagree
Five layers can set the same key, and Anthropic documents the order. From strongest to weakest: managed settings, the JSON passed with --settings on the command line, .claude/settings.local.json, .claude/settings.json, then ~/.claude/settings.json.
That order has a consequence teams should expect: a teammate's personal settings.local.json outranks the repository's settings.json for single values such as the model. Your project setting is a default for them, not a ceiling.
Lists behave differently. Most lists, including permissions.allow, merge across files rather than replacing each other, so a team rule and a personal rule both apply.
If you need a setting a teammate cannot quietly change, the answer is the next section, not a stronger file in the repo. The settings.json guide covers the file locations in detail.
Source: the precedence order and the list-merge note in Explore the .claude directory, read November 18, 2026.
Company-wide policy: managed settings
Managed settings belong to the organization rather than to a repository or a person. Anthropic describes them as the only place for a security team's policy, because no personal settings file can override them.
There are four delivery routes, and the right one depends on how you already manage machines:
- Server-managed settings in the claude.ai admin console or a self-hosted gateway, fetched at startup and polled hourly.
- MDM or OS policy, such as a macOS configuration profile or a Windows
HKLMregistry value through Intune, Jamf or Group Policy. - A
managed-settings.jsonfile in a system directory on each machine, for hosts without device management. - A Windows
HKCUregistry value, for when you cannot write the machine-level key.
Two limits decide which one you need. Claude Code reads one managed source by default and ignores the others. And a cloud session does not read a device's MDM profile or file at all, so policy for cloud sessions has to come from server-managed settings.
The paths, the keys and the check that proves a policy is in force are in the managed settings guide.
Anthropic's admin page is the decision map for the wider rollout: API provider, managed settings, policy enforcement, usage monitoring and data handling.
Sources: "Choose a delivery mechanism" and "Where and when a policy applies" in Deploy managed settings, and Set up Claude Code for your organization, read November 18, 2026.
Onboarding one teammate
- Clone the repository and start Claude Code in it.
- Accept the trust prompt for that folder, after reading what it lists. Until then the allow rules and hooks are dormant.
- Check what loaded.
/contextlists the CLAUDE.md files in context, and/doctorreports configuration problems. - Keep their exceptions local. Anything personal goes in
.claude/settings.local.json, which stays out of git.
Anthropic publishes example settings.json files for a developer, a team and an organization, each with a plain and an annotated tab. The team one is the fastest starting point for a repository's .claude/settings.json.
Sources: Example settings files, and the /context and /doctor checks in Debug your configuration, read November 18, 2026.
Common mistakes
- Committing
settings.local.json. It carries one person's machine-specific approvals and will fight everyone else's. - Expecting the team's allow rules to work on day one. They wait for the trust dialog; deny rules do not.
- Putting a hard requirement in CLAUDE.md. It is guidance. A rule that cannot be skipped belongs in a deny rule or a hook.
- Setting a security policy in the repo. A teammate can override it. Only managed settings hold.
- Piling up rules. Anthropic's own advice is to keep the enforced set small, because every hook and deny rule occasionally fires when it should not, and someone has to maintain it.
Where these answers come from
- The commit table, the precedence order and the list-merge rule: Explore the .claude directory, read November 18, 2026.
- Which rules wait for trust, and who each scope belongs to: Settings and Best practices, read the same day.
- The managed delivery routes and their coverage: Deploy managed settings, read the same day.
- Auto memory being machine-local: How Claude remembers your project, read the same day.
- The example files: Example settings files, read the same day.
Common questions
Is there a team plan setting I have to turn on?
No. A team setup is files in the repository plus, for policy, managed settings — there is nothing to switch on.
How do I share the same agents and commands with another project?
Three documented routes: put them in ~/.claude/ for your own use everywhere, package them as a plugin the team installs, or start Claude Code from the directory that holds them.
What happens to a teammate's personal approvals?
Choosing "Yes, and don't ask again" writes the rule to .claude/settings.local.json, which keeps it on their machine and out of your commits.
Do managed settings reach a cloud session?
Not from the device. A cloud session does not read the MDM profile or managed-settings file, so server-managed settings are what reach it.