Files on Disk
Claude Code keeps its state in plain files.
Some you write, such as settings and CLAUDE.md. Others Claude Code writes, such as transcripts and caches.
This page lists them by place, says what each one is, and links to the page with the details.
At a Glance
| Question | Answer |
|---|---|
| Can you use it? | ✅ Yes. Open any file listed here in an editor. Most are plain JSON, Markdown, or JSONL. |
| Can you change it? | You edit the files marked "You write". Do not edit the files that Claude Code writes. |
| Can you turn it on or off? | CLAUDE_ moves ~/.. cleanup sets the cleanup age. |
| Where does it live? | ~/., ~/., . in a project, and managed folders. |
| Status | Documented Undocumented |
Source: Explore the .claude Directory and the program.
warning
The files are not encrypted.
A secret that a tool prints goes into the transcript, and every prompt you type goes into history.jsonl.
The Big Picture
Files in a Project
You usually commit these files, except the ones marked local.
| Path | Status | You write? | What it is | Page |
|---|---|---|---|---|
. | Documented | ✅ | Shared project settings. | Settings Files and Scopes |
. | Documented | ✅ | Your private project settings. Claude Code adds it to your global git excludes. | Settings Files and Scopes |
CLAUDE. or . | Documented | ✅ | Project instructions. Files in the working folder and each folder above it load at launch. | Memory and Rules |
CLAUDE. | Documented | ✅ | Private project notes. Add it to .. | Memory and Rules |
AGENTS. or . | Documented | ✅ | Read when no CLAUDE. or CLAUDE. is in or above the working folder. | Memory and Rules |
. | Documented | ✅ | Rules. A paths key limits a rule to matching files. | Memory and Rules |
<subfolder>/ | Documented | ✅ | Loads after Claude reads or edits a file in that subfolder. | Memory and Rules |
. | Documented | ✅ | A project skill. | Skills and Commands |
. | Documented | ✅ | A project slash command. Skills replace this form, but it still loads. | Slash Commands |
. | Documented | ✅ | A project subagent. The closest definition wins. | Subagents |
. | Documented | ❌ | Memory of subagents that set memory:. memory: uses .. | Subagent Frontmatter |
. | Documented | ✅ | A project output style. | Output Styles |
. | Documented | ✅ | Project MCP servers. Claude Code asks you to approve them first. | MCP Config |
Files in Your Home Folder
CLAUDE_CONFIG_DIR moves ~/.claude. It does not move ~/.claude.json unless you set the variable.
| Path | Status | You write? | What it is | Page |
|---|---|---|---|---|
~/. | Documented | Mostly no | App state, sign-in data, personal and local MCP servers, and per-project state. Claude Code writes it. | Extra Keys and Global Config |
~/. | Documented | ✅ | Your user settings. | Settings Files and Scopes |
~/. | Documented | ✅ | Your personal instructions for every project. | Memory and Rules |
~/. | Documented | ✅ | Your personal rules. They load before project rules. | Memory and Rules |
~/. | Documented | ✅ | Your personal skills. | Skills and Commands |
~/. | Documented | ❌ | Skills from your claude.ai account. | Skills and Commands |
~/., ~/. | Documented | ❌ | Synced items that were removed. Kept so you can recover them until the retention sweep deletes them. The sweep uses cleanup, which is 30 days by default. | Skills and Commands |
~/. | Documented | ✅ | Your personal slash commands. | Slash Commands |
~/. | Documented | ✅ | Your personal subagents. | Subagents |
~/. | Documented | ✅ | Your personal output styles. | Output Styles |
~/. | Documented | ✅ | Your keyboard shortcuts. Run / to open it. | Slash Commands |
~/. | Documented | ❌ | Memory of subagents that set memory:. | Subagent Frontmatter |
Plugins and Marketplaces
Source: Plugin Loading Reference.
| Path | Status | What it is | Page |
|---|---|---|---|
~/. | Documented | The plugin root. CLAUDE_ sets this parent folder. | Plugin Loading |
plugins/ | Undocumented | One copy of each installed version. | Plugin Loading |
plugins/ | Documented | The folder behind ${CLAUDE_. It survives updates. | Plugin Loading |
plugins/ | Undocumented | The install records. Claude Code may keep dated set- or unreadable copies. | Plugin Loading |
plugins/ | Documented | The marketplace records. | Plugin Loading |
plugins/ | Documented | A clone of each marketplace. | Marketplaces |
plugins/ | Documented | Plugins synced from claude.ai. The id is <name>@synced. | Plugin Loading |
<plugin>/. | Documented | The manifest inside a plugin. | Plugin Manifest |
. | Documented | The catalog inside a marketplace repository. | Marketplaces |
<plugin>/ | Documented | Hooks and mod modules that a plugin ships. | Hooks Configuration |
. | Documented | Type files that Claude Code writes for a mod that you load from a folder. | Files, Nouns, and Gates |
Sessions and Transcripts
All paths here are under ~/.claude/.
<project> is the project folder path with every character other than a letter or digit turned into -.
Source: Explore the .claude Directory.
| Path | Status | What it is | Cleaned by age? |
|---|---|---|---|
projects/ | Documented | The transcript of one session. | ✅ |
projects/ | Documented | Subagent transcripts. | ✅ |
projects/ | Documented | Large tool outputs and MCP images. | ✅ |
projects/ | Documented | Auto memory. MEMORY. is the index. | ❌ |
file- | Documented | Snapshots from before edits, for rewind. | ✅ |
plans/ | Documented | Plan files from plan mode. | ✅ |
tasks/ | Documented | Task lists. | ✅ |
dev- | Documented | Mods that Claude wrote during a session. | ✅ |
uploads/ | Documented | Files attached from the web or mobile app. | ✅ |
debug/ | Documented | Debug logs, written while debug logging is on. | ✅ |
paste- | Documented | Large pastes. | ✅ |
shell-, session- | Documented | Shell setup and per-session metadata. | ✅ |
backups/ | Documented | Copies of ~/.. The five newest stay. | ✅ |
sessions/ | Documented | One small file for each running session. | ❌ |
history. | Documented | Every prompt you typed, for up-arrow and Ctrl+R. | Entries age out |
feedback-, feedback/ | Documented | Feedback archives and drafts that you have not sent. | Drafts age out |
usage- | Documented | Reports from / and their cached data. | ❌ |
The full list, the retention rules, and the controls are on Sessions and Storage. The line format of a transcript is on Transcript Format.
Caches and Account Files
| Path | Status | What it is | Page |
|---|---|---|---|
~/. | Documented | Your login credentials. On macOS, the Keychain holds them, and Claude Code falls back to this file when the Keychain rejects the write. On Linux and Windows, Claude Code uses this file (mode 0600 on Linux). Keep it private and do not delete it. | Sessions and Storage |
~/. | Documented | Totals shown by /. | Sessions and Storage |
~/. | Documented | Cached server-managed settings, or {}. | Enterprise Settings |
~/. | Documented | Cached organization limits. Some account types only. | Enterprise Settings |
~/. | Documented | A cached copy of the changelog for /. | What Changed |
~/., ~/., ~/. | Documented | The list of running background sessions, the state of each session, and its scratch folder. Keep them. The official "Agent View" page describes them. | Sessions and Storage |
state/, mods/, bridge-, seed-, downloads/, cache/ | Undocumented | Seen on a 2. machine or named in the program. No docs page describes them. | Sessions and Storage |
Managed Files
An administrator puts these on the machine. A user cannot override them.
| Path | Status | What it is | Page |
|---|---|---|---|
managed- and managed- | Documented | Organization settings. The folder is next to the file and merges in alphabetical order. | Settings Files and Scopes |
Managed CLAUDE. | Documented | Organization instructions. A user cannot exclude it. | Memory and Rules |
managed- | Documented | A fixed set of MCP servers. It gives the organization exclusive control. | MCP Settings and Policy |
Managed skills <managed dir>/. | Documented | Skills for all users on a machine. They win over personal and project skills. | Skills and Commands |
The folder is /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows.
Settings Precedence
When two settings files set the same key, the higher one wins.
1. Managed settings
2. --settings (command line)
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json
List keys such as permissions.allow merge across files.
The exceptions and the merge rules are on Settings Files and Scopes.
Example
You want to find where Claude Code kept the last session in /work/app, and then remove old ones.
ls ~/.claude/projects/-work-app/
claude purge --dry-run
The first command lists the transcripts of that project.
The second shows what claude purge would delete, without deleting it.