The first hard call you face when bringing Claude Code from a solo workflow into a team is what to do with the .claude/ directory. Commit everything, and you can claim "we all share the same setup" — until somebody's API token or session history ends up in the repo's history. Ignore everything, and the custom commands and subagents you've spent weeks tuning never reach your teammates.
I've been running Claude Code across four personal projects, and started rolling it out to teams on two of them. Along the way I've watched the lack of a clear policy on .claude/ quietly break reproducibility — sometimes by leaking personal info, sometimes by leaving newcomers without the configuration they need. This article is the boundary line I've settled on, expressed as a working policy you can adopt today.
Sort the contents of .claude/ first
Claude Code's .claude/ directory mixes files with very different purposes. Until you've classified them, no Git policy will hold up.
The main pieces are:
settings.json— project-wide configuration (model selection, allowed tools, MCP server definitions)settings.local.json— personal local overrides (gitignore by default)commands/— custom slash commands as.mdfilesagents/— custom subagent definitionsCLAUDE.md— project working knowledge that lives at the top of the repohistory/orsessions/— Claude Code's session logs
The four worth sharing across the team are commands, agents, the shared parts of settings.json, and CLAUDE.md. Everything else stays in personal territory. The decision rule is simple: ask "should every contributor working in this repo run Claude Code with the same behavior here?" If yes, commit it. If no, keep it out.
It helps to picture two layers. The shared layer encodes how the team agrees Claude should act in this codebase. The personal layer holds the credentials and state that make Claude Code work on a specific machine. Mixing the two is what causes both leaks and reproducibility breaks, so name the layers explicitly before writing a single .gitignore line.
The four files worth committing
My rule of thumb is that only configuration that contributes to reproducibility belongs in Git. Four kinds of files clear that bar.
commands/*.md are pointless if they aren't shared. A command like /release that runs your release procedure, or /migrate that scaffolds a migration, is a codified team workflow. There's no reason for each developer to maintain their own copy, so they live in .claude/commands/ at the repo root and improve through pull-request review like any other code. A nice side effect is that you accumulate a kind of "playbook in markdown" — when somebody new joins, the commands directory shows them how the team thinks about routine work.
agents/ carries the same property. A "PR review specialist" subagent or a "test failure triage" subagent embodies decisions about how your team wants Claude to act. If those definitions only exist on one laptop, the productivity gain becomes unrepeatable. Subagents are where you compound expertise — that's exactly the kind of thing version control was built for. Reviewing changes to agent prompts in pull requests has a real ROI, because a single careless edit to a system prompt can quietly degrade the agent for everybody.
CLAUDE.md is the file that hands Claude your project's domain knowledge, coding conventions, and testing strategy in one place. Without it in the repo, every newcomer starts Claude Code from zero context, and the tool can't show what it's actually capable of. If you read The practical guide to Claude Code's settings.json alongside this article, you'll have a fuller picture of which fields are safe to commit.
The shareable part of settings.json covers the allow-list for tools, the model selection, and the URLs/names of MCP servers — anything that doesn't carry secrets. Be deliberate about the model selection in particular: pinning it in the shared file ensures everyone runs the same model on the same prompts, which is what makes "we tried this" conversations meaningful.
What to keep personal — including the mistake I actually made
Equally important is being explicit about what must never be committed. Get this fuzzy and one day a permanent copy of an API key lives in your .git/objects directory.
settings.local.json is the file Claude Code reserves for "personal overrides" — it should already be in your gitignore. That's where personal API tokens and machine-specific allowances belong.
history/ and sessions/ contain your actual conversations with Claude — including failed prompt experiments and any internal information you happened to discuss. Early on I committed .claude/ wholesale and a reviewer caught an OPENAI_API_KEY in the diff right before push. Had it been a git push, I'd have been resetting history with BFG Repo-Cleaner that afternoon. Now I treat the rule "history is private" as non-negotiable, even on solo projects, because the cost of cleanup is enormous compared to the cost of one extra .gitignore line.
Authentication for MCP servers — OAuth tokens, API keys, database connection strings — never gets shared. The shared settings.json should only carry the connection URL and server name; each developer adds their own credentials in settings.local.json. Layering personal mcpServers overrides on top of a shared definition keeps the boundary clean.
A subtler trap is paths. If your shared settings.json references absolute paths from your machine (/Users/yourname/Projects/...), the file works for you and breaks for everyone else. Replace machine-specific paths with environment variables or relative paths before committing.
A working .gitignore template
Here's the pattern I recycle across the four projects.
# Claude Code personal settings
.claude/settings.local.json
.claude/history/
.claude/sessions/
.claude/cache/
.claude/projects/
# Temp / OS-specific files
.claude/*.tmp
.claude/.DS_Store
# Last-line-of-defense for credentials
.claude/secrets.json
.claude/.env*
.claude/**/credentials.json.claude/commands/, .claude/agents/, .claude/settings.json, and CLAUDE.md are explicitly tracked.
After updating .gitignore, run git status -- .claude/ and confirm only the intended files are tracked. Newer Claude Code versions occasionally introduce new subdirectories, so check this once a month. I learned this the hard way when an upgrade added .claude/projects/ and I committed it without realizing. A monthly five-second check is much cheaper than a frantic history rewrite later.
If your repo already has things you'd rather not have committed, deal with that before adopting the new policy. Plain git rm --cached is enough to remove a tracked file from the index without deleting the local copy; for actual secrets, you'll need a history rewrite. Don't paper over the problem by adding the file to .gitignore after it's already tracked.
Rolling it out to the team
When I bring an existing solo Claude Code setup to a team, I follow this order to minimize friction.
- Move personal data (tokens, absolute paths, your email) out of
.claude/settings.jsoninto.claude/settings.local.json. - Set up
.gitignoreand verifygit status -- .claude/is clean. - Audit
commands/andagents/. Keep what the team will actually use; move experiments to_archive/or delete them. - Add a "Read this before using Claude Code in this repo" section at the top of
CLAUDE.md. - Open a pull request so a teammate can review whether anything personal slipped through.
Don't skip step 5. Personal information you've stopped seeing — old directory paths, internal names, sample email addresses — has a way of hiding inside commands/ markdown files. Use the review pass as a "is this OK to publish?" check, not just a technical review.
It also pays to write a one-page onboarding note that explains how a teammate sets up their personal settings.local.json after pulling the repo. Document the credentials they'll need, where to put each one, and how to verify Claude Code launches correctly. Without that note, the first newcomer spends an hour rediscovering things you already know. For the underlying ideas behind a well-tuned CLAUDE.md, CLAUDE.md design patterns — growing project intelligence covers the patterns I rely on when shaping a team-facing version.
Wrapping up — one small step you can take today
The .claude/ Git policy is a foundation you set once and live with for years. You don't need to perfect it today. Add three lines — .claude/settings.local.json, .claude/history/, and .claude/sessions/ — to your .gitignore, run git status -- .claude/, and confirm nothing personal is staged. That alone prevents most of the credential-leak accidents that happen in the wild.
Once you're ready to take it to a team, audit your commands and agents, polish CLAUDE.md, and roll out in that order. In my experience that's the path with the least friction. Claude Code's value compounds when a team works from the same shared context — the .claude/ directory is just the mechanism for getting there.