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.
Source: Explore the .claude Directory and the program.
warning
The files are not encrypted.
A secret that a tool prints goes into the transcript. 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: An official docs page names this item. | ✅ | Shared project settings. | Settings Files and Scopes |
. | Documented: An official docs page names this item. | ✅ | Your private project settings. Claude Code adds it to your global git excludes. | Settings Files and Scopes |
CLAUDE. or . | Documented: An official docs page names this item. | ✅ | Project instructions. Files in the working folder and each folder above it load at launch. | Memory and Rules |
CLAUDE. | Documented: An official docs page names this item. | ✅ | Private project notes. Add it to .. | Memory and Rules |
AGENTS. or . | Documented: An official docs page names this item. | ✅ | Claude Code reads it when no CLAUDE. or CLAUDE. is in or above the working folder. | Memory and Rules |
. | Documented: An official docs page names this item. | ✅ | Rules. A paths key limits a rule to matching files. | Memory and Rules |
<subfolder>/ | Documented: An official docs page names this item. | ✅ | Loads after Claude reads or edits a file in that subfolder. | Memory and Rules |
. | Documented: An official docs page names this item. | ✅ | A project skill. | Skills and Commands |
. | Documented: An official docs page names this item. | ✅ | A project slash command. Skills replace this form, but it still loads. | Slash Commands |
. | Documented: An official docs page names this item. | ✅ | A project subagent. The closest definition wins. | Subagents |
. | Documented: An official docs page names this item. | ❌ | Memory of subagents that set memory:. memory: uses .. | Subagent Frontmatter |
. | Documented: An official docs page names this item. | ✅ | A project output style. | Output Styles |
. | Documented: An official docs page names this item. | ✅ | 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: An official docs page names this item. | 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: An official docs page names this item. | ✅ | Your user settings. | Settings Files and Scopes |
~/. | Documented: An official docs page names this item. | ✅ | Your personal instructions for every project. | Memory and Rules |
~/. | Documented: An official docs page names this item. | ✅ | Your personal rules. They load before project rules. | Memory and Rules |
~/. | Documented: An official docs page names this item. | ✅ | Your personal skills. | Skills and Commands |
~/. | Documented: An official docs page names this item. | ❌ | Skills from your claude.ai account. | Skills and Commands |
~/., ~/. | Documented: An official docs page names this item. | ❌ | Removed synced items. They stay 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: An official docs page names this item. | ✅ | Your personal slash commands. | Slash Commands |
~/. | Documented: An official docs page names this item. | ✅ | Your personal subagents. | Subagents |
~/. | Documented: An official docs page names this item. | ✅ | Your personal output styles. | Output Styles |
~/. | Documented: An official docs page names this item. | ✅ | Your keyboard shortcuts. Run / to open it. | Slash Commands |
~/. | Documented: An official docs page names this item. | ❌ | Memory of subagents that set memory:. | Subagent Frontmatter |
Plugins and Marketplaces
Source: Plugin Loading Reference.
| Path | Status | What it is | Page |
|---|---|---|---|
~/. | Documented: An official docs page names this item. | The plugin root. CLAUDE_ sets this parent folder. | Plugin Loading |
plugins/ | Undocumented: Only the program shows this item. It can change without notice. | One copy of each installed version. | Plugin Loading |
plugins/ | Documented: An official docs page names this item. | The folder behind ${CLAUDE_. It survives updates. | Plugin Loading |
plugins/ | Undocumented: Only the program shows this item. It can change without notice. | The install records. Claude Code may keep dated set- or unreadable copies. | Plugin Loading |
plugins/ | Documented: An official docs page names this item. | The marketplace records. | Plugin Loading |
plugins/ | Documented: An official docs page names this item. | A clone of each marketplace. | Marketplaces |
plugins/ | Documented: An official docs page names this item. | Plugins synced from claude.ai. The id is <name>@synced. | Plugin Loading |
<plugin>/. | Documented: An official docs page names this item. | The manifest inside a plugin. | Plugin Manifest |
. | Documented: An official docs page names this item. | The catalog inside a marketplace repository. | Marketplaces |
<plugin>/ | Documented: An official docs page names this item. | Hooks and mod modules that a plugin ships. | Hooks Configuration |
. | Documented: An official docs page names this item. | 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. In it, - replaces every character other than a letter or digit.
Source: Explore the .claude Directory.
| Path | Status | What it is | Cleaned by age? |
|---|---|---|---|
projects/ | Documented: An official docs page names this item. | The transcript of one session. | ✅ |
projects/ | Documented: An official docs page names this item. | Subagent transcripts. | ✅ |
projects/ | Documented: An official docs page names this item. | Large tool outputs and MCP images. | ✅ |
projects/ | Documented: An official docs page names this item. | Auto memory. MEMORY. is the index. | ❌ |
file- | Documented: An official docs page names this item. | Snapshots from before edits, for rewind. | ✅ |
plans/ | Documented: An official docs page names this item. | Plan files from plan mode. | ✅ |
tasks/ | Documented: An official docs page names this item. | Task lists. | ✅ |
dev- | Documented: An official docs page names this item. | Mods that Claude wrote during a session. | ✅ |
uploads/ | Documented: An official docs page names this item. | Files attached from the web or mobile app. | ✅ |
debug/ | Documented: An official docs page names this item. | Debug logs, written while debug logging is on. | ✅ |
paste- | Documented: An official docs page names this item. | Large pastes. | ✅ |
shell-, session- | Documented: An official docs page names this item. | Shell setup and per-session metadata. | ✅ |
backups/ | Documented: An official docs page names this item. | Copies of ~/.. The five newest stay. | ✅ |
sessions/ | Documented: An official docs page names this item. | One small file for each running session. | ❌ |
history. | Documented: An official docs page names this item. | Every prompt you typed, for up-arrow and Ctrl+R. | Entries age out |
feedback-, feedback/ | Documented: An official docs page names this item. | Feedback archives and drafts that you have not sent. | Drafts age out |
usage- | Documented: An official docs page names this item. | 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: An official docs page names this item. | Your login credentials. On macOS, the Keychain holds them. Claude Code uses 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: An official docs page names this item. | Totals that / shows. | Sessions and Storage |
~/. | Documented: An official docs page names this item. | Cached server-managed settings, or {}. | Enterprise Settings |
~/. | Documented: An official docs page names this item. | Cached organization limits. Some account types only. | Enterprise Settings |
~/. | Documented: An official docs page names this item. | A cached copy of the changelog for /. | What Changed |
~/., ~/., ~/. | Documented: An official docs page names this item. | 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: Only the program shows this item. It can change without notice. | Present on a 2. machine (after 2. was installed, only cache/ and a type file under mods/ were written; bridge-, seed-, and downloads/ are empty and state/ was last written before the install) or named in the program. No docs page describes them. The program describes state/, seed-, bridge-, and cache/; see the link. | Sessions and Storage |
Names in the Config Folder
The tables above show full paths. This table lists each name on its own, so you can look one up.
The paths are under ~/.claude/ unless the Where column says otherwise.
The program holds more names than this table lists. They are internal files, or names with a use that this page could not confirm.
| Name | Status | Where | What it is |
|---|---|---|---|
settings. | Documented: An official docs page names this item. | ~/., . | Your user or project settings. |
keybindings. | Documented: An official docs page names this item. | ~/. | Your keyboard shortcuts. The contexts and actions are on Keybindings. |
commands | Documented: An official docs page names this item. | ~/., . | Slash commands. |
skills | Documented: An official docs page names this item. | ~/., . | Skills. |
rules | Documented: An official docs page names this item. | ~/., . | Rules. |
output- | Documented: An official docs page names this item. | ~/., . | Output styles. |
plugins | Documented: An official docs page names this item. | ~/. | The plugin root. |
agent- | Documented: An official docs page names this item. | ~/., . | Memory of subagents. |
projects | Documented: An official docs page names this item. | ~/. | Transcripts and auto memory, one folder for each project. |
sessions | Documented: An official docs page names this item. | ~/. | One small file for each running session. |
tasks | Documented: An official docs page names this item. | ~/. | Task lists. |
plans | Documented: An official docs page names this item. | ~/. | Plan files from plan mode. |
debug | Documented: An official docs page names this item. | ~/. | Debug logs. |
paste- | Documented: An official docs page names this item. | ~/. | Large pastes. |
uploads | Documented: An official docs page names this item. | ~/. | Files attached from the web or mobile app. |
dev- | Documented: An official docs page names this item. | ~/. | Mods that Claude wrote during a session. |
shell- | Documented: An official docs page names this item. | ~/. | Shell setup. |
backups | Documented: An official docs page names this item. | ~/. | Copies of ~/.. The five newest stay. |
usage- | Documented: An official docs page names this item. | ~/. | Reports from / and their cached data. |
jobs | Documented: An official docs page names this item. | ~/. | The state of background sessions. |
daemon | Documented: An official docs page names this item. | ~/. | The list of running background sessions. |
cache | Documented: An official docs page names this item. | ~/. | Caches, such as changelog.. |
changelog. | Documented: An official docs page names this item. | ~/. | A cached copy of the changelog for /. |
stats- | Documented: An official docs page names this item. | ~/. | Totals that / shows. |
remote- | Documented: An official docs page names this item. | ~/. | Cached server-managed settings. |
policy- | Documented: An official docs page names this item. | ~/. | Cached organization limits. |
feedback- | Documented: An official docs page names this item. | ~/. | Feedback archives. |
drafts | Documented: An official docs page names this item. | ~/. | Feedback drafts that you have not sent. |
state | Undocumented: Only the program shows this item. It can change without notice. | ~/. | Staged settings changes and consent records. See Sessions and Storage. |
seed- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The root for temp folders of cloud-session uploads. See Sessions and Storage. |
model- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | Cached model catalog files and masked-. See Sessions and Storage. |
. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The old place of the global config. The program uses it when it is a non-empty file. Otherwise it uses ~/.. |
. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | Holds an ISO time. The program reads the age of the file to skip a new cleanup run. |
. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | A marker that the deep-link registration failed. The program reads the age of the file. It does not try again for a while. |
. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The result of the last update, with the fields outcome (success or failed), status, version_, version_, and error_. |
. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The update lock. The program treats a lock younger than 5 minutes as held. |
active- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | A ledger of active time, with version 1 and a windows list. |
asset- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The cache of plugin binary assets. |
cowork_ | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The plugin root in place of plugins when CLAUDE_ is on. |
daemon. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The lock file of the daemon. |
daemon. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The log of the daemon. The older copy is daemon.. |
daemon. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | Status that the daemon supervisor writes. It holds the supervisor process id. |
daemon. | Undocumented: Only the program shows this item. It can change without notice. | ~/. | Status that the scheduled-task worker writes. It holds the worker process id. |
gh- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | A cache of pull request statuses from GitHub. |
mcp- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | The MCP needs-auth cache. |
my- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | A cached list of closed issues. Each entry has number, title, and closed. |
startup- | Undocumented: Only the program shows this item. It can change without notice. | ~/. | A . and a . file that CLAUDE_ writes. See Probes. |
Managed Files
An administrator puts these on the machine. A user cannot override them.
| Path | Status | What it is | Page |
|---|---|---|---|
managed- and managed- | Documented: An official docs page names this item. | Organization settings. The folder is next to the file. Its files merge in alphabetical order. | Settings Files and Scopes |
Managed CLAUDE. | Documented: An official docs page names this item. | Organization instructions. A user cannot exclude it. | Memory and Rules |
managed- | Documented: An official docs page names this item. | A fixed set of MCP servers. It gives the organization exclusive control. | MCP Settings and Policy |
Managed skills <managed dir>/. | Documented: An official docs page names this item. | 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. Then you want to 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. It deletes nothing.
Exact Fields
The exact fields of ~/.claude.json are in this schema: https://clawdipedia.cc/schemas/claude-code-claude-json.json. The program builds this payload in code, not with a validator. So the schema comes from that code. A field marked x-unverified has a type that the code does not show. A field marked x-observed is a field that a probe saw.
It lists every field of this release. Build on the fields it names. Look each one up there before you rely on it.