The .claude Folder, Explained: What's Inside It and What to Commit
The first time you notice a .claude folder — in your home directory, or suddenly sitting in a repo — the reasonable questions are: what put it there, what’s inside, and does it belong in git? The short version: it’s Claude Code’s configuration directory, there are two kinds (global and per-project), and mixing up what goes where is behind half the “Claude ignores my rules” complaints I see. Here’s the map.
The two .claude folders
~/.claude (your home directory; %USERPROFILE%\.claude on Windows) is your personal, machine-wide setup. It applies to every project you open.
.claude/ (at a repo’s root) is that project’s setup. It travels with the code, which is exactly why parts of it belong in git.
Both are hidden dotfolders — ls -a shows them in a terminal, and Cmd+Shift+. reveals them in the macOS Finder.
What lives in ~/.claude
The pieces you’ll actually touch:
CLAUDE.md— your global instructions, applied in every project: personal preferences like your shell, commit style, or language defaults. The full craft of writing one is in the CLAUDE.md guide.settings.json— global settings and permission rules. Covered in depth in the settings.json reference.commands/— personal custom slash commands available everywhere.agents/— custom subagent definitions, if you use them.
And the pieces Claude Code manages for itself — session transcripts and history under projects/, todo state, shell snapshots, auto memory. Browse them if you’re curious; don’t hand-edit them. This machine-managed data is also why deleting ~/.claude is not a clean “reset”: you’d wipe your history and memory along with your settings.
What lives in a project’s .claude/
settings.json— team-shared settings and permissions for this repo. Commit it.settings.local.json— your personal overrides for this repo. Claude Code adds it to.gitignoreautomatically; leave it out of commits.commands/— project slash commands (/deploy,/review-migration, whatever your team scripts). Commit them — they’re the cheapest way to share workflow.agents/— project-scoped subagents, same commit-it logic.
The precedence is intuitive once you see the layers: project settings.local.json beats project settings.json, which beats global ~/.claude/settings.json. Specific wins over general.
The classic mistake: CLAUDE.md inside .claude/
A project’s CLAUDE.md goes at the repo root, next to the .claude/ folder — not inside it. Only the global one lives at ~/.claude/CLAUDE.md. If Claude seems to ignore a rules file you swear you wrote, this misplacement is the first thing to check.
Creating one from scratch
There’s no ceremony. mkdir .claude in a repo and start adding files, or let Claude Code create what it needs: /init generates a starter CLAUDE.md at the repo root, and saving any project-scoped setting or command creates .claude/ for you. The global ~/.claude appears the first time you run Claude Code at all.
Quick reference
| File | Location | Commit to git? |
|---|---|---|
| Global instructions | ~/.claude/CLAUDE.md | No (personal) |
| Global settings | ~/.claude/settings.json | No (personal) |
| Project instructions | CLAUDE.md at repo root | Yes |
| Project settings | .claude/settings.json | Yes |
| Personal project overrides | .claude/settings.local.json | Never |
| Project commands / agents | .claude/commands/, .claude/agents/ | Yes |
| History, memory, snapshots | inside ~/.claude | Never (machine-managed) |
One adjacent note, with the disclosure that we build it: if the other half of your Claude life — the claude.ai chats where you plan before the code hits the repo — is an unorganized scroll, NorthLab Folders adds local-first folders to that sidebar too.
Related Claude Code guides
- CLAUDE.md, Explained: The File That Teaches Claude Code Your Rules
- Claude Code settings.json & Permissions: The Practical Reference
- Claude Code Commands: The Cheat Sheet I Wish I’d Had on Day One
- How Claude Code Memory Works
- Claude on Mac: Find Your Projects, Folders & Files
Frequently asked questions
What is the .claude folder?
It’s Claude Code’s configuration directory, and there are two of them. ~/.claude in your home directory holds your personal, global setup — settings, your global CLAUDE.md, custom commands, and session history. A .claude/ folder inside a project holds that repo’s shared configuration — team settings, project slash commands, and personal local overrides.
Where is the .claude folder located?
The global one is ~/.claude on macOS and Linux (%USERPROFILE%\.claude on Windows). The project one is a .claude/ directory at the root of any repo that has one. Both are hidden dotfolders — use ls -a in a terminal, or press Cmd+Shift+. in the macOS Finder to reveal them.
Should I commit the .claude folder to git?
Commit the shareable parts of a project’s .claude/ — settings.json, commands/, and agents/ — so your team gets the same setup. Never commit settings.local.json (Claude Code gitignores it for you; it’s for personal overrides). The global ~/.claude never belongs in a repo.
Is it safe to delete the .claude folder?
Deleting a project’s .claude/ just removes that repo’s Claude Code configuration. Deleting ~/.claude is more destructive — you lose your global settings, global CLAUDE.md, custom commands, and your session history. Claude Code will recreate the folder on next run, but the contents are gone.
Does CLAUDE.md live inside the .claude folder?
Only the global one — your personal ~/.claude/CLAUDE.md. A project’s CLAUDE.md lives at the repo root, next to .claude/, not inside it. Putting it inside .claude/ is the most common misplacement, and Claude Code won’t pick it up there.