# The .claude Folder, Explained: What's Inside It and What to Commit > Claude Code keeps two .claude folders — one in your home directory, one per project. What each file does, which ones to commit to git, and which to never hand-edit. **Source:** [https://northlabapps.com/blog/what-is-the-claude-folder/](https://northlabapps.com/blog/what-is-the-claude-folder/) **Published:** 2026-07-15 **Topics:** claude-code, configuration **Author:** NorthLab Apps (https://northlabapps.com) — makers of NorthLab Folders, a privacy-first folders/search/export extension for ChatGPT and Claude --- 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](https://northlabapps.com/blog/claude-md-complete-guide/). - **`settings.json`** — global settings and permission rules. Covered in depth in the [settings.json reference](https://northlabapps.com/blog/claude-code-settings-json/). - **`commands/`** — personal [custom slash commands](https://northlabapps.com/blog/claude-code-commands-cheat-sheet/) 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](https://northlabapps.com/blog/claude-code-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 `.gitignore` automatically; 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](https://northlabapps.com/folders) adds local-first folders to that sidebar too. ## Related Claude Code guides - [CLAUDE.md, Explained: The File That Teaches Claude Code Your Rules](https://northlabapps.com/blog/claude-md-complete-guide/) - [Claude Code settings.json & Permissions: The Practical Reference](https://northlabapps.com/blog/claude-code-settings-json/) - [Claude Code Commands: The Cheat Sheet I Wish I'd Had on Day One](https://northlabapps.com/blog/claude-code-commands-cheat-sheet/) - [How Claude Code Memory Works](https://northlabapps.com/blog/claude-code-memory/) - [Claude on Mac: Find Your Projects, Folders & Files](https://northlabapps.com/blog/claude-folders-mac/) ## 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.