> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Explore the .claude directory

> Where Claude Code reads CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules, and auto memory. Explore the .claude directory in your project and ~/.claude in your home directory.

Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from `~/.claude` in your home directory. Commit project files to git to share them with your team; files in `~/.claude` are personal configuration that applies across all your projects.

On Windows, `~/.claude` resolves to `%USERPROFILE%\.claude`. If you set [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars), every `~/.claude` path on this page lives under that directory instead. The same applies to `.claude.json`, which otherwise sits at `~/.claude.json`.

Most users only edit `CLAUDE.md` and `settings.json`. If your repository already has an `AGENTS.md` for other coding agents, Claude Code [can read that](https://code.claude.com/docs/en/memory.md#agents-md) in place of a `CLAUDE.md`. The rest of the directory is optional: add skills, rules, or subagents as you need them.

## Explore the directory

Click files in the tree to see what each one does, when it loads, and an example.

Configuration files

**`CLAUDE.md`**

**When it loads**: Loaded into context at session start

Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here.

**`.mcp.json`**

**When it loads**: In interactive sessions, MCP servers you've [approved](https://code.claude.com/docs/en/mcp.md#project-scope) load when the session begins. Tool schemas are deferred by default and load on demand via [tool search](https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search)

Configures Model Context Protocol (MCP) servers that give Claude access to external tools: databases, APIs, browsers, and more. This file holds the project-scoped servers your whole team uses. Personal servers you want to keep to yourself go in `~/.claude.json`.

**`.worktreeinclude`**

**When it loads**: Read when Claude creates a [git worktree](https://code.claude.com/docs/en/worktrees.md) via `--worktree`, the `EnterWorktree` tool, or subagent `isolation: worktree`

Lists gitignored files to copy from your main repository into each new worktree. Worktrees are fresh checkouts, so untracked files like `.env` are missing by default. Patterns here use `.gitignore` syntax. Only files that match a pattern and are also gitignored get copied.

**`.claude/`**

Project settings, rules, skills, subagents, and other configuration. If you use git, commit most of these files so your team shares them, and keep personal ones such as `settings.local.json` out of your commits.

**`.claude/settings.json`**

**When it loads**: Read at session start. Most edits [apply to the running session](https://code.claude.com/docs/en/settings.md#when-edits-take-effect)

Settings that Claude Code applies directly. Permissions control which commands and tools Claude can use; hooks run your scripts at specific points in a session. Unlike CLAUDE.md, which Claude reads as guidance, these are enforced whether Claude follows them or not.

This file ranks above `~/.claude/settings.json` and below `.claude/settings.local.json`, the `--settings` flag, and managed settings in [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence). For most single-value keys, such as `model`, Claude Code uses the highest-ranked value. Most lists, such as `permissions.allow`, [merge across files](https://code.claude.com/docs/en/settings.md#lists-merge-instead-of-overriding).

**`.claude/settings.local.json`**

**When it loads**: Read at session start. Most edits [apply to the running session](https://code.claude.com/docs/en/settings.md#when-edits-take-effect)

Your personal settings for this project. Same JSON format as `settings.json`, gitignored when Claude Code saves a setting to it.

This file ranks above `.claude/settings.json` and below the `--settings` flag and managed settings in [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence). For most single-value keys, such as `model`, Claude Code uses the highest-ranked value. Most lists, such as `permissions.allow`, [merge across files](https://code.claude.com/docs/en/settings.md#lists-merge-instead-of-overriding).

**`.claude/rules/`**

**When it loads**: Rules without `paths:` frontmatter load at session start. Rules with `paths:` load when Claude reads, writes, or edits a matching file

Project instructions split into topic files. Like CLAUDE.md, rules are guidance that Claude Code doesn't enforce. For enforced behavior use [hooks](https://code.claude.com/docs/en/hooks.md) or [permissions](https://code.claude.com/docs/en/permissions.md).

**`.claude/skills/`**

**When it loads**: Invoked with `/skill-name` or when Claude matches the task to a skill

Each skill is a folder with a `SKILL.md` file plus any supporting files it needs. By default, both you and Claude can invoke a skill. Use [frontmatter](https://code.claude.com/docs/en/skills.md#frontmatter-reference) to control that: `disable-model-invocation: true` so Claude can't invoke a skill like `/deploy` on its own, or `user-invocable: false` so only Claude can invoke the skill.

**`.claude/commands/`**

**When it loads**: Invoked with `/command-name` or when Claude matches the task to a command

Holds single-file commands: a prompt saved as `.claude/commands/deploy.md` runs as `/deploy`. For a new command, use a [skill](#ce-skills), which can bundle reference docs, templates, or scripts alongside the prompt.

**`.claude/output-styles/`**

**When it loads**: Read at startup in the terminal, so restart Claude Code after you add or edit a style

Each Markdown file defines an [output style](https://code.claude.com/docs/en/output-styles.md#how-output-styles-work), a set of instructions that adjusts how Claude works. Put a style here if your team shares it, like a review mode everyone uses. See [`~/.claude/output-styles/`](#ce-global-output-styles) for how to select one.

**`.claude/agents/`**

**When it loads**: Each subagent runs in its own context window when you or Claude invoke it

Each Markdown file with `name` and `description` frontmatter defines a subagent with its own system prompt, tool access, and optionally its own model. Useful for parallel work or isolated tasks.

**`.claude/workflows/`**

**When it loads**: Loaded at startup when [workflows are on](https://code.claude.com/docs/en/workflows.md). Each saved workflow runs as a `/<name>` command

Each `.js` file is a [dynamic workflow](https://code.claude.com/docs/en/workflows.md): a script the runtime executes to spawn and coordinate many subagents. To add one, have Claude write a workflow, then run `/workflows` in the session and save it here.

**`.claude/agent-memory/`**

**When it loads**: First 200 lines of a subagent's `MEMORY.md`, capped at 25KB, loaded into its system prompt when the subagent runs

Subagents with [`memory: project`](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory) in their frontmatter get a dedicated memory directory here while [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) is on. Each subagent reads and writes its own `MEMORY.md`, separate from your main session's auto memory in `~/.claude/projects/`.

**`.claude/agent-memory/<agent-name>/MEMORY.md`**

**When it loads**: First 200 lines, capped at 25KB, loaded into the subagent's system prompt when the subagent runs

An index of the notes the subagent has saved. The subagent creates and updates this file itself, in the same format as your main [auto memory](https://code.claude.com/docs/en/memory.md#storage-location) index.

**`~/.claude.json`**

**When it loads**: Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change a [global config option](https://code.claude.com/docs/en/settings-reference.md#global-config-settings) in `/config` or trust a project folder

Holds account details, per-project trust decisions, your personal MCP servers, and UI toggles.

**`~/.claude/`**

The global counterpart to your project [`.claude/`](#ce-dot-claude) directory. Configuration files in this directory apply to you in every project on this machine.

**`~/.claude/CLAUDE.md`**

**When it loads**: Loaded at session start in every project on this machine

Your global instruction file. Loaded alongside the project CLAUDE.md. If the two conflict, Claude may follow either one. Keep this file to preferences that apply everywhere: response style, commit format, personal conventions.

**`~/.claude/settings.json`**

**When it loads**: Read at session start. Most edits [apply to the running session](https://code.claude.com/docs/en/settings.md#when-edits-take-effect)

Same format as project `settings.json`: permissions, hooks, model, and environment variables. Put settings here that you want in every project, like allow rules, a preferred model, or a notification hook.

This file ranks below the project's settings files, the `--settings` flag, and managed settings in [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence). For most single-value keys, such as `model`, Claude Code uses the highest-ranked value. Most lists, such as `permissions.allow`, [merge across files](https://code.claude.com/docs/en/settings.md#lists-merge-instead-of-overriding).

**`~/.claude/keybindings.json`**

**When it loads**: Read at session start and hot-reloaded when you edit the file

Rebind keyboard shortcuts in the interactive CLI. Run `/keybindings` in a session to create or open this file. Check the [reserved shortcuts](https://code.claude.com/docs/en/keybindings.md#reserved-shortcuts) before you pick a key.

**`~/.claude/themes/`**

**When it loads**: Read at session start and [hot-reloaded](https://code.claude.com/docs/en/terminal-config.md#create-a-custom-theme) when files change. Listed in `/theme`

Each `.json` file defines a custom color theme: a built-in `base` preset plus an `overrides` map of color tokens. Run `/theme` in a session to create one, or write the JSON yourself. Selecting a custom theme stores `custom:<slug>` as your theme preference.

**`~/.claude/projects/`**

**When it loads**: The current project's `memory/MEMORY.md` loads at session start while auto memory is on. The topic files it lists are read on demand

Holds [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory), the notes Claude saves across sessions: your role and preferences, corrections you give it, project decisions, and where to find information outside the project. Each project gets its own memory directory keyed by the repository path.

**`~/.claude/projects/<project>/memory/MEMORY.md`**

**When it loads**: First 200 lines, capped at 25KB, loaded at session start while [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) is on

An index pointing to topic files for detail. Claude creates and updates this file as it works. You can edit or delete it.

**`~/.claude/projects/<project>/memory/user_role.md`**

**When it loads**: Claude reads this when a related task comes up

An example of a topic file. Claude saves each memory in its own topic file, picks the filename, and lists it in `MEMORY.md`.

**`~/.claude/rules/`**

**When it loads**: Rules without `paths:` frontmatter load at session start. Rules with `paths:` load when Claude reads, writes, or edits a matching file

Same format as project [`.claude/rules/`](#ce-rules), applied to every project on this machine. Use this for conventions you want across all your work, like personal code style or commit message format.

**`~/.claude/skills/`**

**When it loads**: Invoked with `/skill-name` or when Claude matches the task to a skill

Skills you built for yourself, available in all your projects on this machine. Same format as project [`.claude/skills/`](#ce-skills).

**`~/.claude/commands/`**

**When it loads**: Invoked with `/command-name` or when Claude matches the task to a command

Same format as project [`.claude/commands/`](#ce-commands), available in all your projects on this machine.

**`~/.claude/output-styles/`**

**When it loads**: Read at startup in the terminal, so restart Claude Code after you add or edit a style

Each Markdown file defines an [output style](https://code.claude.com/docs/en/output-styles.md#how-output-styles-work), a set of instructions that adjusts how Claude works. Use a style to adapt Claude Code for uses beyond coding, or to add teaching or review modes.

Select a built-in or custom style with `/output-style` or `/config` in a session, or with the `outputStyle` key in settings. Styles here are available in every project on this machine. If a project style has the same name, Claude Code uses the project's style.

**`~/.claude/agents/`**

**When it loads**: Each subagent runs in its own context window when you or Claude invoke it

Subagents defined here are available across all your projects on this machine. Same format as project [`.claude/agents/`](#ce-agents).

**`~/.claude/workflows/`**

**When it loads**: Loaded at startup when [workflows are on](https://code.claude.com/docs/en/workflows.md). Each saved workflow runs as a `/<name>` command

Workflow scripts saved here are available across all your projects on this machine. A project workflow with the same name in `.claude/workflows/` takes precedence.

**`~/.claude/agent-memory/`**

**When it loads**: First 200 lines of a subagent's `MEMORY.md`, capped at 25KB, loaded into its system prompt when the subagent runs

Subagents with `memory: user` in their frontmatter store knowledge here while [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) is on. That knowledge persists across all projects. For project-scoped subagent memory, see [`.claude/agent-memory/`](#ce-agent-memory).

## What's not shown

The explorer covers files you author and edit. A few related files live elsewhere:

| File | Location | Purpose |
| - | - | - |
| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that your own settings files and `--settings` values can't override, apart from [narrow exceptions](https://code.claude.com/docs/en/settings.md#exceptions-to-managed-settings-precedence). See [where to save the file](https://code.claude.com/docs/en/managed-settings.md#deploy-a-managed-settings-file) and [which managed source Claude Code uses](https://code.claude.com/docs/en/managed-settings.md#precedence-within-the-managed-tier). |
| `CLAUDE.local.md` | Project root | Your private preferences for this project, loaded alongside CLAUDE.md. Create it manually and add it to `.gitignore`. |
| `AGENTS.md` | Project root, `.claude/`, or any directory | Project instructions you write for AI coding agents. Claude Code can [load it](https://code.claude.com/docs/en/memory.md#agents-md) in place of a `CLAUDE.md`. |
| Installed plugins | `~/.claude/plugins` | Cloned marketplaces, installed plugin versions, the `installed_plugins.json` install record, and per-plugin data, managed by `claude plugin` commands. Plugins [synced from your claude.ai account](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) download into `~/.claude/plugins/synced/`. For a plugin installed from a marketplace [`command` source](https://code.claude.com/docs/en/plugins/marketplace-reference#command-plugin-source) in link mode, Claude Code stores links here instead of a copy, and the plugin's files stay in the directory the command prints. A `command` source requires Claude Code v2.1.229 or later. A plugin listed by relative path in a marketplace you added from a local path also [loads in place](https://code.claude.com/docs/en/plugins/loading.md#find-plugins-on-disk) from its source directory rather than from a cache copy. See [plugin caching](https://code.claude.com/docs/en/plugins/loading.md#find-plugins-on-disk) for how orphaned versions are cleaned up. |

`~/.claude` also holds data Claude Code writes as you work: transcripts, prompt history, file snapshots, caches, and logs. See [application data](#application-data) below.

## Choose the right file

Different kinds of customization live in different files. Use this table to find where a change belongs.

| You want to | Edit | Scope | Reference |
| :- | :- | :- | :- |
| Give Claude project context and conventions | `CLAUDE.md` | project or global | [Memory](https://code.claude.com/docs/en/memory.md) |
| Allow or block specific tool calls | `settings.json` `permissions` or `hooks` | project or global | [Permissions](https://code.claude.com/docs/en/permissions.md), [Hooks](https://code.claude.com/docs/en/hooks.md) |
| Run a script before or after tool calls | `settings.json` `hooks` | project or global | [Hooks](https://code.claude.com/docs/en/hooks.md) |
| Set environment variables for the session | `settings.json` `env` | project or global | [Settings](https://code.claude.com/docs/en/settings-reference.md#all-settings) |
| Keep personal overrides out of git | `settings.local.json` | project only | [Settings scopes](https://code.claude.com/docs/en/settings.md#where-settings-live) |
| Add a prompt or capability you invoke with `/name` | `skills/<name>/SKILL.md` | project or global | [Skills](https://code.claude.com/docs/en/skills.md) |
| Define a specialized subagent with its own tools | `agents/*.md` | project or global | [Subagents](https://code.claude.com/docs/en/sub-agents.md) |
| Orchestrate many subagents from a script | `workflows/*.js` | project or global | [Dynamic workflows](https://code.claude.com/docs/en/workflows.md) |
| Connect external tools over MCP | `.mcp.json` | project only | [MCP](https://code.claude.com/docs/en/mcp.md) |
| Change how Claude formats responses | `output-styles/*.md` | project or global | [Output styles](https://code.claude.com/docs/en/output-styles.md) |

## File reference

This table lists every file the explorer covers. Project-scope files live in your repo under `.claude/` (or at the root for `CLAUDE.md`, `.mcp.json`, and `.worktreeinclude`). Global-scope files live in `~/.claude/` and apply across all projects.

> [!NOTE]
>
> Several things can override what you put in these files:
>
> * [Managed settings](https://code.claude.com/docs/en/server-managed-settings.md) deployed by your organization take precedence over every settings file and `--settings` value, apart from the [exceptions under Settings precedence](https://code.claude.com/docs/en/settings.md#exceptions-to-managed-settings-precedence)
> * CLI flags like `--permission-mode` or `--settings` override `settings.json` for that session
> * Some environment variables take precedence over their equivalent setting, but this varies: check the [environment variables reference](https://code.claude.com/docs/en/env-vars.md) for each one
>
> See [settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) for the full order.

Click a filename to open that node in the explorer above.

| File | Scope | Commit | What it does | Reference |
| - | - | - | - | - |
| [`CLAUDE.md`](#ce-claude-md) | Project and global | ✓ | Instructions loaded every session | [Memory](https://code.claude.com/docs/en/memory.md) |
| [`rules/*.md`](#ce-rules) | Project and global | ✓ | Topic-scoped instructions, optionally path-gated | [Rules](https://code.claude.com/docs/en/memory.md#organize-rules-with-claude/rules/) |
| [`settings.json`](#ce-settings-json) | Project and global | ✓ | Permissions, hooks, env vars, model defaults | [Settings](https://code.claude.com/docs/en/settings.md) |
| [`settings.local.json`](#ce-settings-local-json) | Project only | | Your personal overrides, gitignored when Claude Code saves a setting to it | [Settings scopes](https://code.claude.com/docs/en/settings.md#where-settings-live) |
| [`.mcp.json`](#ce-mcp-json) | Project only | ✓ | Team-shared MCP servers | [MCP scopes](https://code.claude.com/docs/en/mcp.md#mcp-installation-scopes) |
| [`.worktreeinclude`](#ce-worktreeinclude) | Project only | ✓ | Gitignored files to copy into new worktrees | [Worktrees](https://code.claude.com/docs/en/worktrees.md#copy-gitignored-files-into-worktrees) |
| [`skills/<name>/SKILL.md`](#ce-skills) | Project and global | ✓ | Reusable prompts invoked with `/name` or auto-invoked | [Skills](https://code.claude.com/docs/en/skills.md) |
| [`commands/*.md`](#ce-commands) | Project and global | ✓ | Single-file prompts; same mechanism as skills | [Skills](https://code.claude.com/docs/en/skills.md) |
| [`output-styles/*.md`](#ce-output-styles) | Project and global | ✓ | Custom instruction sets that adjust how Claude works | [Output styles](https://code.claude.com/docs/en/output-styles.md) |
| [`agents/*.md`](#ce-agents) | Project and global | ✓ | Subagent definitions with their own prompt and tools | [Subagents](https://code.claude.com/docs/en/sub-agents.md) |
| [`workflows/*.js`](#ce-workflows) | Project and global | ✓ | Dynamic workflow scripts written by Claude and saved from `/workflows`; each saved workflow runs as a `/<name>` command | [Dynamic workflows](https://code.claude.com/docs/en/workflows.md) |
| [`agent-memory/<name>/`](#ce-agent-memory) | Project and global | ✓ | Persistent memory for subagents | [Persistent memory](https://code.claude.com/docs/en/sub-agents.md#enable-persistent-memory) |
| [`~/.claude.json`](#ce-claude-json) | Global only | | App state, account details, UI toggles, personal MCP servers. If it's missing, Claude Code creates it when you start a session or run a subcommand such as `claude auth status`, but not for `--version` or `--help`. | [Global config](https://code.claude.com/docs/en/settings-reference.md#global-config-settings) |
| [`projects/<project>/memory/`](#ce-global-projects) | Global only | | Auto memory: Claude's notes to itself across sessions | [Auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) |
| [`keybindings.json`](#ce-keybindings) | Global only | | Custom keyboard shortcuts | [Keybindings](https://code.claude.com/docs/en/keybindings.md) |
| [`themes/*.json`](#ce-themes) | Global only | | Custom color themes | [Custom themes](https://code.claude.com/docs/en/terminal-config.md#create-a-custom-theme) |

## Frontmatter fields by file

Skills, command files, subagents, output styles, and rules read their configuration from YAML [frontmatter](https://code.claude.com/docs/en/glossary.md#frontmatter) at the top of the file, and each accepts its own set of fields. This table lists the field names for each file and links to the reference that describes them.

| File | Frontmatter fields | Reference |
| - | - | - |
| `skills/<name>/SKILL.md` | `name`, `description`, `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context`, `agent`, `background`, `hooks`, `paths`, `shell`, `metadata`, `license`, `compatibility` | [Skill frontmatter](https://code.claude.com/docs/en/skills.md#frontmatter-reference) |
| `commands/*.md` | The skill fields except `name` and `paths` | [Skill frontmatter](https://code.claude.com/docs/en/skills.md#frontmatter-reference) |
| `agents/*.md` | `name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `autoCompactWindow`, `skills`, `mcpServers`, `hooks`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`, `omitClaudeMd`, `experimental` | [Subagent frontmatter](https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields) |
| `output-styles/*.md` | `name`, `description`, `keep-coding-instructions`, `force-for-plugin` | [Output style frontmatter](https://code.claude.com/docs/en/output-styles.md#frontmatter) |
| `rules/*.md` | `paths` | [Rule frontmatter](https://code.claude.com/docs/en/memory.md#rules-frontmatter-reference) |

Agents shipped in a [plugin](https://code.claude.com/docs/en/plugins/components.md#agents) honor a subset of the subagent fields.

## Troubleshoot configuration

If a setting, hook, or file isn't taking effect, see [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md) for the inspection commands and a symptom-first lookup table.

## Application data

Beyond the config you author, `~/.claude` holds data Claude Code writes during sessions. These files are plaintext. Anything that passes through a tool is written to a transcript on disk: file contents, command output, pasted text.

The transcript can also hold what Claude Code sends the model with your messages:

* The system prompt
* Tool definitions
* Request parameters
* The instruction files it loaded, such as CLAUDE.md

### Cleaned up automatically

Claude Code deletes the files in the paths below once they're older than [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays), as long as it can safely determine the retention period. The default is 30 days and the minimum is 1; setting `0` fails with a validation error. The same age cutoff applies to automatic removal of [orphaned worktrees](https://code.claude.com/docs/en/worktrees.md#clean-up-subagent-and-background-session-worktrees).

| Path under `~/.claude/` | Contents |
| - | - |
| `projects/<project>/<session>.jsonl` | Conversation transcript: messages, tool calls, and tool results, plus the system prompt, tool definitions, and parameters of the requests Claude Code sent the model |
| `projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`, `projects/<project>/<session>.jsonl.superseded-<timestamp>` | A previous transcript for the session that Claude Code set aside instead of overwriting or deleting it. It doesn't appear in the session picker |
| `projects/<project>/<session>/subagents/` | [Subagent](https://code.claude.com/docs/en/sub-agents.md) transcripts in the same format as the session transcript, removed with the parent session transcript when it ages out |
| `projects/<project>/<session>/tool-results/` | Large tool outputs spilled to separate files, and full-size copies of [images that MCP tools return](https://code.claude.com/docs/en/mcp.md#images-in-tool-results) |
| `projects/<project>/<session>/mcp-tasks/` | What a resumed session needs to follow its running [MCP tasks](https://code.claude.com/docs/en/mcp.md#mcp-tasks-that-run-on-the-server) again, and the results of finished tasks that Claude hasn't read yet |
| `file-history/<session>/` | Pre-edit snapshots of files Claude changed, used for [checkpoint restore](https://code.claude.com/docs/en/checkpointing.md). Holds snapshots for the 100 most recent checkpoints; snapshot files that no retained checkpoint references are deleted, except each file's first snapshot |
| `plans/` | Plan files written during [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) |
| `debug/` | Per-session debug logs, written while debug logging is on, such as when you start with [`--debug`](https://code.claude.com/docs/en/cli-reference#cli-flags) or run `/debug` |
| `paste-cache/` | Contents of large pastes |
| `image-cache/<session>/` | Attached images saved by Claude Code v2.1.274 and earlier. Later versions save pasted and attached images outside `~/.claude`, in an `images/` directory for each session under the temp directory that [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/en/env-vars) controls. The sweep removes other sessions' leftover directories here, whatever their age. |
| `uploads/<session>/` | Files you attach from the web or mobile app, and photos you attach from the mobile app, when messaging a [Remote Control](https://code.claude.com/docs/en/remote-control.md) session. An attachment to a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md) is saved in that session's own cloud environment instead, not on your machine. |
| `dev-mods/<session>/` | [Mods that Claude wrote](https://code.claude.com/docs/en/plugins/mods/create.md#ask-claude-for-a-mod) during the session |
| `session-env/` | Per-session environment metadata |
| `tasks/` | Task lists written by the task tools, one directory per list |
| `shell-snapshots/` | Aliases, functions, and shell options captured at startup and applied by the [Bash tool](https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior) to each command. Removed on clean exit. The sweep clears any left after a crash. |
| `backups/` | Earlier versions of `~/.claude.json`, copied when Claude Code rewrites the file. Claude Code keeps the five newest copies, plus a copy of any version it couldn't parse. Past the age cutoff, the last copy that holds your configuration is deleted too. If the current file parses, holds your configuration, and is under 8 MiB, you're left with a new copy of it. |
| `feedback-bundles/` | Redacted transcript archives written by `/feedback` on third-party providers or when no Anthropic credentials are configured, for sending to your Anthropic account team |
| `feedback/drafts/` | Queued [Claude-drafted feedback](https://code.claude.com/docs/en/tools-reference.md#sendfeedback-tool-behavior) awaiting your review in `/feedback`. Swept after `cleanupPeriodDays` or 30 days, whichever is shorter. When the queue is at its 10-draft limit, Claude Code deletes the oldest draft to make room. |
| `usage-data/` | `report.html` and timestamped report copies written by [`/insights`](https://code.claude.com/docs/en/costs#analyze-your-usage-patterns), plus cached per-session analysis data used to build them |
| `skills/.trash/`, `plugins/.trash/` | [Skills](https://code.claude.com/docs/en/skills.md#how-synced-skills-behave) and [plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) that the claude.ai sync removed, such as after you turn one off on claude.ai or stop syncing. The files stay here so you can recover them until the sweep deletes them |
| `plugins/installed_plugins.set-aside.<date>.<hash>.json`, `plugins/installed_plugins.unreadable.<date>.<hash>.kept` | Dated copies Claude Code makes before rewriting [`installed_plugins.json`](https://code.claude.com/docs/en/plugins/loading#find-plugins-on-disk): install records it dropped, and the contents of a file it couldn't read. |
| `plugins/mcpb/` | The files Claude Code extracted from the [MCP bundles](https://code.claude.com/docs/en/plugins/components.md#include-a-packaged-mcpb-server) that plugins declare. A bundle's age counts from the last session that used it. |
| `todos/`, `statsig/`, `logs/` | Legacy directories from older versions. No longer written. The sweep removes their contents and then the empty directory. |

Session files in `sessions/`, auto memory, and Claude Desktop and Cowork transcripts each follow their own retention rule:

* **`sessions/`**: holds one small file per running session, used to detect concurrent sessions and crashes. It isn't part of the age-based sweep: Claude Code removes each file when its session exits and clears crash leftovers on the next launch.
* **`seed-admin/`**: scratch git directories Claude Code makes while packaging your repository for an [ultrareview](https://code.claude.com/docs/en/ultrareview.md) or a [cloud session upload](https://code.claude.com/docs/en/claude-code-on-the-web.md#send-local-repositories-without-github). When an upload ends, or in a later session if it was interrupted, Claude Code removes that upload's directory and leaves `seed-admin/` in place.
* **Auto memory**: the sweep doesn't delete the memory files in a project's [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) directory, `projects/<project>/memory/`. Claude Code removes that directory only if it has been empty for the whole retention period. Before v2.1.228, the sweep treated folders inside the memory directory as session data and could delete old files beneath it.
* **Claude Desktop and Cowork transcripts**: Claude Code keeps the transcript of a session you started or most recently continued in Claude Desktop or Cowork at any age. To give these transcripts an age limit, set [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#desktopsessioncleanupperioddays). Requires Claude Code v2.1.248 or later; earlier versions delete them after `cleanupPeriodDays`.

  Claude Code deletes these transcripts after `cleanupPeriodDays` instead in cases such as these:

  * [Managed settings](https://code.claude.com/docs/en/managed-settings.md) set `cleanupPeriodDays`
  * The [HIPAA configuration applies to your sessions](https://code.claude.com/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect)

Claude Code skips the age-based sweep in these cases:

* **Bare mode**: when you run `claude -p` with [`--bare`](https://code.claude.com/docs/en/headless#start-faster-with-bare-mode), Claude Code doesn't run the sweep in that session.
* **Paused sweep**: if Claude Code can't safely determine the retention period, it pauses the sweep; the [`retention_sweep` event](https://code.claude.com/docs/en/monitoring-usage#retention-sweep-event) lists each configuration that pauses it. When the cause is a settings file that can't be read or parsed, or settings errors with `cleanupPeriodDays` or `desktopSessionCleanupPeriodDays` set, `/status` shows a warning until you fix the cause.

When [managed settings](https://code.claude.com/docs/en/managed-settings.md) provide `cleanupPeriodDays`, Claude Code runs the sweep at the managed value even when a lower-priority settings file has errors.

To check that the machines in your organization run the sweep with the retention period you set, see [Check the retention sweep](https://code.claude.com/docs/en/monitoring-usage.md#check-the-retention-sweep).

### Session scratchpad directory

The scratchpad is a per-session directory that Claude Code gives Claude for temporary files: intermediate results, helper scripts, and drafts that don't belong in your project. When Claude says it saved something "to the scratchpad", the file is there. Claude uses it instead of `/tmp`, and can create, edit, and read files in it without a permission prompt.

The scratchpad lives under Claude Code's temp directory rather than `~/.claude`. Find the current session's path for your platform:

* **macOS**: `/private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/`
* **Linux**: `/tmp/claude-<uid>/<project>/<session-id>/scratchpad/`, or the same shape under `$TMPDIR` when your system sets one
* **Windows**: `%TEMP%\claude\<project>\<session-id>\scratchpad\`

`<project>` is your working directory path with every character other than letters and digits replaced by `-`, such as `-Users-you-my-project`. On Windows, `<project>` is a 16-character hash of that string, such as `73295dabccd14c56`. In a Desktop app session, it can be the string itself. To get the exact path, ask Claude. If you set [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/en/env-vars), the tree moves under that directory instead. Hooks receive the current session's path as [`scratchpad_dir`](https://code.claude.com/docs/en/hooks#common-input-fields).

Scratchpad files last as long as the session's transcript: the [retention sweep](#cleaned-up-automatically) deletes the directory when it deletes the transcript, and [`claude purge`](#clear-local-data) doesn't touch the temp directory. Because the directory sits under the system temp location, your operating system can also clear it, such as on restart. To keep something Claude wrote there, ask Claude to move it into your project.

A session has a scratchpad only when all of these hold:

* You're signed in with a claude.ai account rather than an API key
* The session uses the Anthropic API, not Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry
* [`enableArtifact`](https://code.claude.com/docs/en/settings-reference#enableartifact) isn't set to `false`

### Kept until you delete them

Apart from the rows that say otherwise, the retention cleanup sweep doesn't remove the paths below, and Claude Code keeps them until you delete them.

| Path under `~/.claude/` | Contents |
| - | - |
| `history.jsonl` | Prompts you've typed, with timestamp and project path. Used for up-arrow recall, `Ctrl+R` history search, and `!` shell-command completion. Each sweep removes the entries older than `cleanupPeriodDays` when the [HIPAA configuration applies to your sessions](https://code.claude.com/docs/en/hipaa-setup.md#check-how-developers-sign-in-and-connect). |
| `stats-cache.json` | Aggregated token and cost counts shown by `/usage` |
| `remote-settings.json` | Cached copy of [server-managed settings](https://code.claude.com/docs/en/server-managed-settings.md) for your organization, or `{}` when your organization has configured none. Only present when the session [fetches them](https://code.claude.com/docs/en/server-managed-settings.md#platform-availability). Claude Code checks for updates at startup and hourly during a session. Claude Code deletes it when you log out. |
| `cache/changelog.md` | Cached copy of the Claude Code changelog, shown by `/release-notes`. Refreshed in the background. |
| `policy-limits.json` | Cached feature policy settings for your organization. Only present for some account types. Refreshed automatically. A `policy-limits.json.stamp.json` sidecar records which account or API key the cache belongs to. Claude Code deletes both files when you log out. |

#### State files to keep

Depending on which features you use, `~/.claude/` also holds files that the tables under [Application data](#application-data) don't list. Of those, caches and lock files are safe to delete. Keep these state files:

* `.credentials.json`: your [login credentials](https://code.claude.com/docs/en/authentication.md#credential-management)
* `agent-memory/`: [subagent memory](https://code.claude.com/docs/en/sub-agents.md#enable-persistent-memory)
* `jobs/` and `daemon/`: [background session](https://code.claude.com/docs/en/agent-view.md#where-state-is-stored) state

### Plaintext storage

Transcripts and history are not encrypted at rest. OS file permissions are the only protection. If a tool reads a `.env` file or a command prints a credential, that value is written to `projects/<project>/<session>.jsonl`. To reduce exposure:

* Lower `cleanupPeriodDays` to shorten how long Claude Code keeps transcripts
* Set [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#desktopsessioncleanupperioddays) to give Claude Desktop and Cowork transcripts an age limit too
* Set the [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/en/env-vars) environment variable to skip writing transcripts and prompt history in any mode. In non-interactive mode, you can instead pass `--no-session-persistence` alongside `-p`, or set `persistSession: false` in the TypeScript Agent SDK; the Python SDK has no equivalent option.
* Use [permission rules](https://code.claude.com/docs/en/permissions.md) to deny reads of credential files

### Clear local data

Run `claude purge` to delete the state Claude Code holds for one project. It deletes:

* Transcripts and auto memory under `projects/`
* Per-session `tasks/`, `debug/`, and `file-history/` entries
* Matching prompt lines in `history.jsonl`
* The project's entry in `~/.claude.json`

Images you pasted or attached in the project's sessions and each session's [scratchpad](#session-scratchpad-directory) are stored under Claude Code's temp directory rather than `~/.claude`, so the purge doesn't remove them. The [retention sweep](#cleaned-up-automatically) still deletes the images once they're older than `cleanupPeriodDays`; a purged session's scratchpad stays until you delete it or your operating system clears the temp directory.

The command prints the full deletion plan and asks for confirmation before removing anything.

Before v2.1.288, the command was `claude project purge`.

The examples below use `~/work/my-repo` as a placeholder. Replace it with the path to your project. If no state matches the path, the command prints an error and exits with status 1.

Preview the plan without deleting anything:

```bash theme={null}
claude purge ~/work/my-repo --dry-run
```

The plan lists each matching item and why it is included:

```text theme={null}
Purge plan for /home/user/work/my-repo:

  dir:    /home/user/.claude/projects/-home-user-work-my-repo
           project transcripts (.jsonl) and memory/
  config: projects["/home/user/work/my-repo"]
           project entry in ~/.claude.json (trust, history, MCP servers)
  filter: /home/user/.claude/history.jsonl
           12 prompt(s) typed in this project

shell-snapshots/ are not project-scoped and will not be touched
backups/ may still contain this project entry in old .claude.json snapshots (/home/user/.claude/backups); at most 5 are kept and they rotate out automatically
Dry run: 3 item(s) would be deleted.
```

Delete with a single confirmation prompt:

```bash theme={null}
claude purge ~/work/my-repo
```

The command prints the same plan, then asks `Delete 3 item(s) for /home/user/work/my-repo? This cannot be undone. [y/N]` and deletes only if you answer `y`.

Omit the path to pick a project from an interactive list.

Skip the confirmation prompt for use in scripts:

```bash theme={null}
claude purge ~/work/my-repo --yes
```

Other options:

* Pass `--all` instead of a path to purge state for every project at once, which deletes `history.jsonl` outright rather than filtering it.
* Pass `-i` to step through the deletion plan one item at a time.

The command leaves `shell-snapshots/` and `backups/` alone because those are not project-scoped, and warns about them in the plan output. If anyone ran [`/heapdump`](https://code.claude.com/docs/en/troubleshooting#high-cpu-or-memory-usage) on the machine, delete the `.heapsnapshot` files it wrote too. A heap snapshot contains the full conversation and any credentials the process held, and neither the retention sweep nor the purge touches it.

You can also delete any of the application-data paths above yourself, apart from the [state files to keep](#state-files-to-keep).

| Delete | You lose |
| - | - |
| `~/.claude/projects/` | Resume, continue, and rewind for past sessions, and auto memory for every project |
| `~/.claude/history.jsonl` | Up-arrow prompt recall, `Ctrl+R` history search, and `!` shell-command completion |
| `~/.claude/paste-cache/` | Pasted text in recalled prompts; see [paste large content](https://code.claude.com/docs/en/terminal-config.md#paste-large-content) |
| `~/.claude/uploads/` | Attachments that past [Remote Control](https://code.claude.com/docs/en/remote-control.md) sessions refer to by path |
| `~/.claude/file-history/` | Checkpoint restore for past sessions |
| `~/.claude/stats-cache.json` | Historical totals shown by `/usage` |
| `~/.claude/usage-data/` | Past [`/insights`](https://code.claude.com/docs/en/costs#analyze-your-usage-patterns) reports and the cached analysis data used to build them |
| `~/.claude/feedback-bundles/` | Feedback and bug-report archives you haven't yet sent to your Anthropic account team |
| `~/.claude/feedback/drafts/` | [Claude-drafted feedback](https://code.claude.com/docs/en/tools-reference.md#sendfeedback-tool-behavior) you haven't sent |
| `~/.claude/remote-settings.json` | Nothing. Re-fetched on next launch. |
| `~/.claude/cache/changelog.md` | Nothing. Refreshed in the background. |
| `~/.claude/policy-limits.json` | Nothing. Refreshed automatically. |
| `~/.claude/tasks/` | Your [task lists](https://code.claude.com/docs/en/interactive-mode.md#task-list), including any still in use |
| `~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/` | The chance to recover [synced skills](https://code.claude.com/docs/en/skills.md#how-synced-skills-behave) and [synced plugins](https://code.claude.com/docs/en/plugins/loading.md#synced-plugins) that Claude Code removed |
| `~/.claude/plugins/installed_plugins.set-aside.<date>.<hash>.json`, `~/.claude/plugins/installed_plugins.unreadable.<date>.<hash>.kept` | The copies of plugin install records that Claude Code dropped or couldn't read. Nothing reads them back |
| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/` | Nothing user-facing |
| `~/.claude/backups/` | The earlier copies you can [restore `~/.claude.json` from](https://code.claude.com/docs/en/errors#configuration-error-in-claude-json) |
| `~/.claude/todos/`, `~/.claude/statsig/`, `~/.claude/logs/`, `~/.claude/image-cache/` | Nothing. Legacy directories not written by current versions. |

Don't delete `~/.claude.json`, `~/.claude/settings.json`, or `~/.claude/plugins/`: those hold your account details, preferences, and installed plugins.

## Related resources

* [Manage Claude's memory](https://code.claude.com/docs/en/memory.md): write and organize CLAUDE.md, rules, and auto memory
* [Configure settings](https://code.claude.com/docs/en/settings.md): set permissions, hooks, environment variables, and model defaults
* [Create skills](https://code.claude.com/docs/en/skills.md): build reusable prompts and workflows
* [Configure subagents](https://code.claude.com/docs/en/sub-agents.md): define specialized agents with their own context
