51  51. The .claude Folders and Settings Files

Claude Code keeps its configuration in two hidden folders, both named .claude: one inside your project and one in your home directory. This page shows what lives where, which files to commit to Git, and how settings files work together.

51.1 Two .claude folders

As of Oct 6, 2026 · Official docs: Explore the .claude directory

Project folder: .claude/ User folder: ~/.claude/
Where Inside your project, e.g. club-events/.claude/ In your home directory
Applies to This project only Every project you open
Shared? Yes: most files in it are committed to Git so teammates get them No: personal, never committed

Both names start with a dot, so both folders are hidden (see Files, Folders, and Paths). Use ls -a to see them:

ls -a ~/.claude

~/.claude is /Users/maria/.claude.

~/.claude is /c/Users/sam/.claude (Windows writes it as C:\Users\sam\.claude).

A new project has no .claude/ folder until you, or Claude Code, create one. Installing Claude Code doesn’t create any settings file either: Claude Code writes ~/.claude/settings.json the first time you change certain options in /config, and .claude/settings.local.json the first time you answer a permission prompt with “Yes, and don’t ask again”. Most people only ever edit two files: CLAUDE.md and settings.json.

51.2 Inside the project

As of Oct 6, 2026 · Official docs: Explore the .claude directory

club-events/                      (your project)
├── CLAUDE.md                     project instructions                commit
├── CLAUDE.local.md               your private instructions           keep private
├── .mcp.json                     MCP servers the team uses           commit
└── .claude/
    ├── settings.json             team settings                       commit
    ├── settings.local.json       your personal setting overrides     keep private
    ├── rules/                    topic-specific instructions         commit
    ├── skills/                   project skills (<name>/SKILL.md)    commit
    ├── agents/                   custom subagents                    commit
    ├── commands/                 older one-file /commands            commit
    ├── output-styles/            shared output styles                commit
    ├── workflows/                saved dynamic workflows             commit
    └── agent-memory/             memory for subagents (Claude writes it)
  • CLAUDE.md and rules/ are covered on CLAUDE.md and Memory. CLAUDE.md may also live at .claude/CLAUDE.md.
  • .mcp.json sits at the project root, not inside .claude/. It lists the MCP servers (connections to other tools and services) that the whole team uses (MCP Servers).
  • skills/, agents/, commands/, output-styles/, workflows/ hold extensions covered in the Extending part (Extending Claude Code: The Big Picture). commands/ is the older way to make a /command; new ones should be skills.
  • You may also meet .worktreeinclude and .claude/worktrees/, used when Claude works in Git worktrees (Git Worktrees and Parallel AI Agents).

51.3 Inside your home folder

As of Oct 6, 2026 · Official docs: Explore the .claude directory

~/                                (your home directory)
├── .claude.json                  app state: login, trusted folders, your MCP servers
└── .claude/
    ├── CLAUDE.md                 your instructions for every project
    ├── settings.json             your settings for every project
    ├── keybindings.json          custom keyboard shortcuts
    ├── rules/ skills/ agents/ commands/ output-styles/ workflows/
    │                             personal versions, available in every project
    ├── themes/                   custom color themes
    ├── plugins/                  installed plugins
    └── projects/                 per project: conversation transcripts
                                  and auto memory (Claude writes these)

Watch out for two look-alike names:

  • ~/.claude.json is a file in your home directory. Claude Code manages it for you: your login session, which folders you trusted, MCP servers you added just for yourself, and a few interface toggles. You rarely edit it.
  • ~/.claude/settings.json is a file inside the ~/.claude/ folder. Your personal settings (permissions, env, model, …) go here. Settings such as permissions typed into ~/.claude.json by mistake are ignored.

As you work, Claude Code also writes data into ~/.claude:

Path What it holds
projects/<project>/<session>.jsonl The full transcript of each conversation (used to resume and rewind)
file-history/ Copies of files from before Claude edited them (used by checkpoints)
plans/ Plans written in plan mode
history.jsonl Every prompt you typed (for the up arrow and Ctrl+R)

Transcripts, file copies, and plans are deleted after 30 days by default (the cleanupPeriodDays setting); history.jsonl stays until you delete it. These files are plain text, not encrypted. If Claude reads your .env file or a command prints a password, that text ends up in a transcript on your disk, which is one more reason to block reads of secret files with a deny rule (below).

To delete what Claude Code saved about one project, run claude purge <path-to-project>; add --dry-run first to see what it would delete. Don’t delete ~/.claude.json, ~/.claude/settings.json, or ~/.claude/plugins/: they hold your login, preferences, and plugins.

51.4 What to commit, and what to keep private

As of Oct 6, 2026 · Official docs: Explore the .claude directory · Settings files and precedence

Commit to Git (shared with the team) Keep private (never commit)
CLAUDE.md CLAUDE.local.md
.claude/settings.json .claude/settings.local.json
.claude/rules/, skills/, agents/, commands/, output-styles/, workflows/ Everything in ~/.claude/, and ~/.claude.json
.mcp.json API keys and passwords, in any file

Claude Code helps with one of these: when it writes .claude/settings.local.json inside a Git repository, it adds **/.claude/settings.local.json to your global Git ignore file, so that file stays out of your commits. If you create .claude/settings.local.json or CLAUDE.local.md by hand, add them to the project’s .gitignore yourself (see .gitignore and Keeping Secrets Out of Git):

echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore

51.5 Settings files and which one wins

As of Oct 6, 2026 · Official docs: Settings files and precedence

Settings are JSON keys that change how Claude Code behaves: which model it starts with, what it may do without asking, which environment variables to set, and much more. A key can be set in several places. When the same key is set in more than one, the higher level in this list wins:

Highest priority
 1. Managed settings   set by an organization's IT department; can't be overridden
 2. Command line       flags such as --model or --settings   (this session only)
 3. Project local      .claude/settings.local.json            (you, this project)
 4. Shared project     .claude/settings.json                  (everyone in the project)
 5. User               ~/.claude/settings.json                (you, every project)
Lowest priority
  • Lists combine. List settings such as permissions.allow are merged from all the files, so each file can add rules. Single values such as model come from the highest level that sets them.
  • Deny always wins. A permission rule that denies something blocks it even if a file at any other level allows it.
  • Start Claude Code in the project’s top folder. Claude Code reads .claude/settings.json from the folder you start it in, not from parent folders (unlike CLAUDE.md files, which also load from parent folders).

Notice the difference from CLAUDE.md: all CLAUDE.md files are loaded and read together, while settings files override each other key by key.

51.6 An example settings.json

As of Oct 6, 2026 · Official docs: Settings files and precedence · Configure permissions · All settings

Maria and Sam commit this small .claude/settings.json to their project:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}
Key What it does
$schema Optional. Lets editors such as VS Code autocomplete and check the file.
model Sessions in this project start on the sonnet model (anyone can still switch with /model).
permissions.allow Run any npm run ... script and any git diff command without asking. A * matches any text.
permissions.ask Always ask before a git push.
permissions.deny Stop Claude from reading .env and .env.something (files that hold secrets) with its file tools or commands like cat .env.
env Environment variables for the session and the commands it runs: here, give slow commands 5 minutes (300,000 ms) instead of the default 2.

Rules are written as Tool or Tool(details). Unlike CLAUDE.md, these are enforced by Claude Code itself. When you answer “Yes, and don’t ask again” to a prompt for a command, Claude Code saves an allow rule in .claude/settings.local.json for you. The full rule syntax and permission modes are on Permissions, Modes, and Safety; the official example settings files page has bigger examples.

Settings files are strict JSON

No comments (//) and no comma after the last item of a list or object. A mistake makes Claude Code show a Settings Error the next time it starts. And never put API keys or passwords in a settings file you commit.

51.7 Checking and changing settings: /config and /status

As of Oct 6, 2026 · Official docs: Settings files and precedence · Debug your configuration

Command What it does
/config Opens the Settings screen. Its Config tab has common personal options (theme, editor mode, verbose output, …) and saves your changes for you, mostly to ~/.claude/settings.json. You can also set one option directly: /config theme=dark.
/status The Status tab: version, model, account, and a Setting sources line listing which settings files loaded.
/permissions Lists every allow, ask, and deny rule and the file it came from; add or remove rules.
/context Shows what fills the context window, including which CLAUDE.md files loaded.
claude doctor Typed in the terminal (not in a session): checks your installation and finds invalid settings files.

Claude Code notices when you save a settings file and applies most changes, such as permissions, right away. A few keys are read only when a session starts; the ones you will meet are model and effort. To change those mid-session, use /model and /effort (Context, Models, Effort, and Usage).

Symptom Likely cause Fix
Your global permission rules are ignored They are in ~/.claude.json Move them to ~/.claude/settings.json
A value in .claude/settings.json seems ignored The same key is set in .claude/settings.local.json, which wins Check /status and your local file
Allow rules a teammate committed don’t work for you Allow rules in .claude/settings.json apply only after you accept the “trust this folder” prompt (deny and ask rules apply right away) Trust the folder when Claude Code asks
MCP servers in .mcp.json never load The file is inside .claude/ Move it to the project root
A skill doesn’t show up It is saved as .claude/skills/name.md Use a folder: .claude/skills/name/SKILL.md

To check whether your configuration causes a problem, run claude --safe-mode. It starts a session with your customizations (CLAUDE.md, skills, plugins, hooks, MCP servers, and more) turned off.

Practice Questions

Easy

Question 1 · Multiple choice

Where do your personal settings for every project go?

  1. .claude/settings.json
  2. ~/.claude/settings.json
  3. ~/.claude.json
  4. .claude/settings.local.json

b. ~/.claude/settings.json is the user settings file. .claude/settings.json (a) is the team’s file for one project, ~/.claude.json (c) holds app state that Claude Code manages (settings like permissions there are ignored), and .claude/settings.local.json (d) is personal but only for one project.

Question 2 · Write the command

You run ls in your home directory and don’t see the .claude folder. Why? Write a command that lists the contents of ~/.claude, including hidden items.

Names that start with a dot are hidden, and plain ls doesn’t show them.

ls -a ~/.claude

(ls -a ~ would show .claude itself among your home folder’s hidden items.)

Question 3 · True or false

You should commit .claude/settings.local.json so your teammates get the same setup.

False. .claude/settings.local.json holds your personal overrides for one project and should stay out of Git. Shared team settings go in .claude/settings.json, which you do commit.

Question 4 · Ordering

Put these settings levels in order from highest priority to lowest: user (~/.claude/settings.json), managed settings, shared project (.claude/settings.json), command line, project local (.claude/settings.local.json).

  1. Managed settings
  2. Command line
  3. Project local (.claude/settings.local.json)
  4. Shared project (.claude/settings.json)
  5. User (~/.claude/settings.json)

The more specific to you and this session, the higher it ranks, except that an organization’s managed settings beat everything.

Question 5 · Matching

Match each item with what it holds.

Item Holds
1. .mcp.json (project root) A. Your conversation transcripts and auto memory
2. ~/.claude.json B. MCP servers shared by the team
3. .claude/rules/ C. App state such as your login and trusted folders
4. ~/.claude/projects/ D. Topic-specific instruction files
5. .claude/settings.local.json E. Your personal setting overrides for one project

1 → B, 2 → C, 3 → D, 4 → A, 5 → E.

Question 6 · Short answer

What does /status tell you about your settings?

Its Status tab shows your version, model, and account, plus a Setting sources line that lists which settings files Claude Code loaded for this session (for example user settings and project local settings). It tells you which files loaded, not which file supplied each key.

Medium

Question 7 · Write the path

Write the full path of Sam’s user settings file as Git Bash shows it, and as Windows shows it. (Sam’s Windows user name is sam.)

  • Git Bash: /c/Users/sam/.claude/settings.json (or ~/.claude/settings.json)
  • Windows: C:\Users\sam\.claude\settings.json

Question 8 · Predict

Maria’s settings files contain:

  • ~/.claude/settings.json: "model": "opus"
  • .claude/settings.json: "model": "sonnet"
  • .claude/settings.local.json: "model": "haiku"

Which model does a session in this project start on if she types claude? Which if she types claude --model opus?

  • claude: haiku. Project local beats shared project, which beats user.
  • claude --model opus: opus. The command line beats all three files, for that session only.

Question 9 · Find the bug

Sam saved this ~/.claude/settings.json, and Claude Code now shows a Settings Error at startup. Find the two problems and fix them.

{
  // use Sonnet to save money
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)",
    ]
  }
}
  1. // use Sonnet to save money is a comment; settings files are strict JSON and don’t allow comments.
  2. There is a trailing comma after "Bash(git diff *)", the last item in the list.

Fixed:

{
  "model": "sonnet",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git diff *)"
    ]
  }
}

Question 10 · Write the JSON

Write a settings file that lets Claude run npm test (with or without extra arguments) without asking, and stops Claude from reading anything inside the project’s secrets/ folder.

{
  "permissions": {
    "allow": [
      "Bash(npm test *)"
    ],
    "deny": [
      "Read(./secrets/**)"
    ]
  }
}

Bash(npm test *) matches npm test and npm test followed by anything (a trailing * also matches the bare command). Read(./secrets/**) matches every file under secrets/.

Question 11 · Scenario

Sam answers a permission prompt for npm run build with “Yes, and don’t ask again”. Where is that choice saved, and will his teammates get it when they pull from GitHub?

Claude Code saves it as an allow rule in .claude/settings.local.json in the project. That file is personal and kept out of Git (Claude Code adds it to Sam’s global Git ignore file), so his teammates won’t get it. To share the rule, he would add it to .claude/settings.json and commit that.

Question 12 · Predict

Maria’s user settings allow Bash(git push *). The project’s .claude/settings.json denies Bash(git push *). What happens when Claude tries to run git push origin main?

It is blocked. Deny rules are checked before allow rules, and a deny from any level wins over an allow from any other level. Maria’s personal allow can’t override the project’s deny.

Question 13 · Scenario

Maria’s user settings allow Bash(git diff *), and the project’s .claude/settings.json (which she has trusted) allows Bash(npm run *). Which of these commands run without a prompt: git diff, npm run dev, npm install?

git diff and npm run dev run without asking. List settings such as permissions.allow are merged across files, so both rules apply. npm install matches neither rule, so it goes through the normal permission check for the current mode (in Manual mode, Claude Code asks you).

Question 14 · Classify

For each file, say “commit” or “keep private”: CLAUDE.md, CLAUDE.local.md, .claude/settings.json, .claude/settings.local.json, .mcp.json, .claude/skills/deploy/SKILL.md, ~/.claude/settings.json.

  • Commit: CLAUDE.md, .claude/settings.json, .mcp.json, .claude/skills/deploy/SKILL.md
  • Keep private: CLAUDE.local.md, .claude/settings.local.json, ~/.claude/settings.json (it isn’t even in the project folder)

Hard

Question 15 · Scenario

Sam wants a deny rule for every project, so he opens ~/.claude.json and adds a "permissions" section. Claude ignores it. Explain why and what he should do.

~/.claude.json is Claude Code’s app-state file (login, trusted folders, personal MCP servers, UI toggles). Settings such as permissions, hooks, and env are not read from it. Sam should put the rule in ~/.claude/settings.json, the user settings file inside the ~/.claude/ folder. The two names look alike but are different files in different places.

Question 16 · Scenario

A teammate committed .claude/settings.json with an allow rule for Bash(npm run *) and a deny rule for Read(./.env). Claude Code applies the deny rule as soon as Maria opens the cloned project, but applies the allow rule only after she accepts the “trust this folder” prompt. Why does it treat the two rules differently?

Allow rules grant capability: they let Claude run commands without asking. A repository you just downloaded could contain anything, so Claude Code won’t let it grant itself extra power until you have looked at it and said you trust it (the trust prompt lists the rules it would turn on). Deny and ask rules only restrict what Claude can do, so applying them immediately can only make you safer.

Question 17 · Scenario

In the middle of a session, Sam changes "model": "sonnet" to "model": "opus" in the project’s .claude/settings.json. Claude keeps using Sonnet. Why, and how can he switch now?

Claude Code reloads most settings when a file changes, but it reads model only when a session starts. The edit applies to the next session. To switch now he should run /model opus (which also saves Opus as his own default) or use the /model picker and press s for this session only.

Question 18 · Compare

Maria wants Claude to never run git push in her project. Compare writing “Never run git push” in CLAUDE.md with adding a deny rule Bash(git push *) to .claude/settings.json.

  • CLAUDE.md is guidance: Claude reads it and usually follows it, but nothing enforces it, and it may be forgotten in a long session.
  • A deny rule is enforced by Claude Code: matching commands are blocked no matter what Claude decides. (Rules match the command as written, so a push written in an unusual way could slip past; hooks and sandboxing add stronger protection, see Permissions, Modes, and Safety.)

For “must never happen” rules, use the deny rule. CLAUDE.md is for “how we do things here”.

Question 19 · Write the JSON

The team’s .claude/settings.json sets "model": "sonnet", but Maria wants Opus for herself in this project without changing anything for her teammates. Which file should she edit, and what should it contain?

.claude/settings.local.json in the project (personal, not committed, and higher priority than the shared file):

{
  "model": "opus"
}

Her user file ~/.claude/settings.json would not work: user settings rank below the project’s shared settings.

Question 20 · Long answer

Explain why Claude Code’s transcripts can be a privacy risk, and list three things you can do about it.

Claude Code saves each conversation as a plain-text transcript under ~/.claude/projects/. Everything that passes through a tool is included: file contents Claude read, command output, pasted text. If Claude reads a .env file or a command prints a password, that secret is now stored, unencrypted, on your disk.

Things you can do:

  1. Add deny rules such as Read(./.env) so Claude doesn’t read secret files in the first place.
  2. Keep secrets out of prompts and pasted text.
  3. Lower cleanupPeriodDays so transcripts are deleted sooner than the default 30 days.
  4. Run claude purge <project-path> to delete what Claude Code saved about a project.

Challenge

Question 21 · Hands-on

Explore your own setup:

  1. Run ls -a ~/.claude and identify three items from this page.
  2. In a practice project, start Claude Code and run /status. Which setting sources are listed?
  3. Create .claude/settings.json with a deny rule for Read(./notes.txt) (create a notes.txt file too), then ask Claude to read notes.txt. What happens?
  4. Run /permissions and find your rule and the file it came from.

Answers depend on your computer. Typically you will see items such as settings.json, projects/, and plugins/ in ~/.claude. After step 3, Claude Code blocks Claude’s attempts to read notes.txt with its Read tool (or with a command such as cat notes.txt) and reports that a deny rule blocked it, even if you ask directly. In /permissions, the rule appears with .claude/settings.json as its source. (Settings changes apply right away, so you don’t need to restart.)

© 2025-2026 Y. Rosenthal. All rights reserved.