Project vs Local vs User Settings

Claude Code gives you three settings files to write to. They look alike but do different jobs. Put each setting in the right place and your whole team stays sane.

User settings

Path: ~/.claude/settings.json. This applies to every project you open. Use it for your own broad defaults — the model you like, whether you want the co-authored line in commits, and other personal habits. Nobody else sees it.

Project settings

Path: .claude/settings.json, inside the repo. This file is checked into git, so everyone on the team gets it. Use it for shared rules: permissions the whole team should have, environment variables the project needs, and hooks like auto-format on save.

{
  "permissions": {
    "allow": ["Bash(npm run test:*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Local settings

Path: .claude/settings.local.json. This is your personal file for one project, and it should stay out of git. Use it for tweaks that only make sense for you — a permission you want but the team doesn't need, or a value you're testing.

How they combine

When the same key appears in more than one file, local beats project, and project beats user. So the team's project file sets the shared baseline, and your local file quietly overrides bits of it for you.

A simple rule of thumb

Ask: should the whole team get this? Put it in the project file. Is it just for me, in this repo? Local file. Is it my habit everywhere? User file. Get that split right and you rarely fight your own config.