Sharing Team Settings Safely

Sharing Claude Code settings with your team is powerful, but only if you split what's shared from what's private. Get the split right and everyone gets the same helpful setup without leaking secrets or stepping on each other.

Commit the project file

The project file, .claude/settings.json, is meant to be checked into git. It's the right home for rules the whole team should have:

• Shared permissions for safe commands.
• Environment values the project needs to run.
• Hooks like auto-format or run-tests.
• A pinned model and commit style.

Because it's committed, every clone of the repo gets it. That's the whole point — one file, one shared setup.

Keep the local file out of git

The local file, .claude/settings.local.json, is for you alone. Put your personal tweaks here — a permission the team doesn't need, a value you're testing. This file should be gitignored so it never lands in the shared repo.

# .gitignore
.claude/settings.local.json

Never commit secrets

This is the big one. The project file is shared, so treat it like a public notice board. Do not put API keys, tokens, or passwords in it — or in the env block there. Anyone with repo access would see them.

For a real key, use apiKeyHelper to fetch it at runtime from a source that stays off git. That keeps the key out of your history entirely.

A simple checklist

Before you commit a settings change, ask:

• Should everyone get this? Project file.
• Is it just for me? Local file, gitignored.
• Is it a secret? Neither — load it with apiKeyHelper.

Stick to that and your team shares the good parts of your setup while the private parts stay private.