Where apps hide your files

Claude Code's settings and CLAUDE.md files

Updated 2026-10-28 · 6 min read

Claude Code spreads its configuration across a hidden ~/.claude folder, a hidden ~/.claude.json file and a few files inside each project. This guide lists each one, what it controls, and which are safe to touch.

The locations

Claude Code's user-level files are in a hidden folder in your home directory, plus one hidden file next to it:

~/.claude/settings.json
~/.claude/CLAUDE.md
~/.claude.json

File	What it holds
~/.claude/settings.json	Your settings for every project: permissions, hooks, environment variables, model defaults.
~/.claude/CLAUDE.md	Instructions Claude loads in every session.
~/.claude.json	App state Claude Code writes for itself: account details, per-project state such as trust decisions, and MCP servers you added for yourself. Not meant to be hand-edited.

Installing Claude Code does not create settings.json; it appears the first time you change an option that is stored there. Open the folder with Go > Go to Folder (⇧⌘G) and ~/.claude, or in Terminal:

open ~/.claude

~/.claude.json sits in your home folder, not inside ~/.claude. If you set the CLAUDE_CONFIG_DIR environment variable, Claude Code stores settings, session history and plugins in that directory instead.

Project files

Inside a project folder, Claude Code looks for:

File	Purpose
.claude/settings.json	Shared project settings. Commit it so teammates get the same permissions and hooks.
.claude/settings.local.json	Your personal overrides for this project. Claude Code keeps it out of git when it creates it.
CLAUDE.md or .claude/CLAUDE.md	Team instructions for the project.
CLAUDE.local.md	Your private project notes, loaded beside CLAUDE.md. Add it to .gitignore yourself.
.mcp.json	MCP servers shared with the team.

When a key is set in more than one place, the highest level wins: managed settings, then a --settings flag, then project local, then shared project, then user. List-type settings such as permissions.allow are combined instead of replaced. Run /status inside Claude Code to see which settings files it loaded.

Where the MCP config is

It depends on the scope you added a server with. Per Anthropic's docs:

Scope	Stored in
Local (the default)	~/.claude.json, under that project's path
Project	.mcp.json in the project root
User	~/.claude.json

So a server you added with claude mcp add is usually in ~/.claude.json, not in a file named mcp. To see them without opening the file, use:

claude mcp list

~/.claude.json can contain tokens and headers for your servers, so do not paste it into a chat, a bug report or a repository. Claude Desktop is a different app with its own claude_desktop_config.json.

Managed settings and CLAUDE.md

Organisations can deploy policy files. On macOS the documented folder is:

/Library/Application Support/ClaudeCode/

It can contain managed-settings.json, a managed-settings.d folder, managed-mcp.json and a managed CLAUDE.md. Organisations can also push the same settings through a configuration profile (the com.anthropic.claudecode preference domain) or from the claude.ai admin console. The folder did not exist on the Mac used for this guide, which is normal for a personal machine. Apart from a few security-related exceptions, nothing in your own files overrides a managed setting.

What else lives in ~/.claude

The same folder fills up with data Claude Code writes as you work. On the Mac used for this guide it held projects/, file-history/, plugins/, skills/, backups/, paste-cache/, session-env/, shell-snapshots/, history.jsonl and stats-cache.json, among others.

Path	Contents	Safe to remove?
projects/<project>/<session>.jsonl	Conversation transcripts. The <project> folder is the project path with non-alphanumeric characters turned into dashes.	Yes, but you lose resume and rewind for those sessions.
projects/<project>/memory/	Claude's auto memory for that project.	Keep it unless you want Claude to forget.
file-history/	Pre-edit snapshots used for checkpoint restore.	Yes, you lose restore for old sessions.
history.jsonl	Prompts you typed, for up-arrow recall.	Yes, you lose recall.
backups/	The five newest earlier copies of ~/.claude.json.	Yes, but they are your way back if that file breaks, and they rotate on their own.
plugins/, skills/	Installed plugins and your skills.	No.

Anthropic's docs say transcripts are deleted automatically once older than cleanupPeriodDays, which defaults to 30. Those files are plain text and can contain anything a tool printed, including secrets from a file it read, so treat projects/ as sensitive. For one project, claude purge <path> shows a deletion plan and asks before removing anything; run it with --dry-run first. It removes that project's auto memory and its entry in ~/.claude.json (trust and MCP servers) as well as transcripts. Versions before 2.1.288 call it claude project purge.

Check sizes before deleting anything:

du -sh ~/.claude/* | sort -h | tail

Editing safely

Settings files are strict JSON. A comment or a trailing comma is an error, and Claude Code reports it at the next start. Claude Code watches the files and applies most edits to a running session. If ~/.claude.json ever fails to parse, Claude Code copies the broken file into ~/.claude/backups/ and offers to reset, and you can copy back one of the recent backups.

Do not delete ~/.claude.json, ~/.claude/settings.json or ~/.claude/plugins/. They hold your account, preferences and installed plugins.

Moving to a new Mac

Copy ~/.claude/settings.json, ~/.claude/CLAUDE.md, the skills/ folder, and any agents/, commands/ or rules/ folders you made. Install plugins again with Claude Code, and sign in on the new Mac instead of copying credentials. Re-add MCP servers with claude mcp add, since they live inside ~/.claude.json, which also holds per-machine state.

Why Finder and Spotlight searches miss them

~/.claude and ~/.claude.json are dot-names, hidden from Finder and left out of Spotlight and Finder searches. From Terminal, ls -la ~ | grep claude shows both.

Finding every copy later

Project settings are scattered across repositories, so typing settings.local.json or CLAUDE.md into Everywhere lists all of them in one go, including hidden .claude folders (projects in Documents or Desktop appear once it has Full Disk Access). Typing .mcp.json finds each project's MCP file. It matches names only, so it will not show what a file sets. Press ⌘↵ to reveal one in Finder.

Common questions

Where is the Claude Code settings.json on a Mac?

User settings are in ~/.claude/settings.json. Per-project settings are in .claude/settings.json (shared) and .claude/settings.local.json (personal) inside the project.

Where does Claude Code store MCP server config?

In ~/.claude.json for local and user scope, and in .mcp.json at the project root for servers shared with a team. claude mcp list shows them without opening files.

Where is the global CLAUDE.md?

At ~/.claude/CLAUDE.md. A project can have CLAUDE.md or .claude/CLAUDE.md, and CLAUDE.local.md for private notes.

Can I delete ~/.claude to free space?

Not the whole folder. Transcripts in projects/, file-history/ and history.jsonl can go at the cost of resume and history, but settings.json, plugins/ and ~/.claude.json hold your setup.