Explore the .claude directory - Claude Code Docs
Skip to main content
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, 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 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.

​
What’s not shown

The explorer covers files you author and edit. A few related files live elsewhere: ~/.claude also holds data Claude Code writes as you work: transcripts, prompt history, file snapshots, caches, and logs. See application data below.

​
Choose the right file

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

​
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.
Several things can override what you put in these files:See settings precedence for the full order.
Click a filename to open that node in the explorer above.

​
Frontmatter fields by file

Skills, command files, subagents, output styles, and rules read their configuration from YAML 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. Agents shipped in a plugin honor a subset of the subagent fields.

​
Troubleshoot configuration

If a setting, hook, or file isn’t taking effect, see Debug your configuration 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, 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. 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.
  • Auto memory: the sweep doesn’t delete the memory files in a project’s 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. Requires Claude Code v2.1.248 or later; earlier versions delete them after cleanupPeriodDays. Claude Code deletes these transcripts after cleanupPeriodDays instead in either of these cases:
Claude Code skips the age-based sweep in these cases:
  • Bare mode: when you run claude -p with --bare, 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 retention cleanup sweep; the 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 explicitly set, Claude Code also shows a warning in /status until you fix the settings errors. When managed settings provide cleanupPeriodDays, Claude Code runs the sweep at the managed value in either case.
To check that the machines in your organization run the sweep with the retention period you set, see 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. If you set CLAUDE_CODE_TMPDIR, the tree moves under that directory instead. Hooks receive the current session’s path as scratchpad_dir. Scratchpad files last as long as the session’s transcript: the retention sweep deletes the directory when it deletes the transcript, and claude purge 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 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.

​
State files to keep

Depending on which features you use, ~/.claude/ also holds files that the tables under Application data don’t list. Of those, caches and lock files are safe to delete. Keep these state files:

​
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 to give Claude Desktop and Cowork transcripts an age limit too
  • Set the CLAUDE_CODE_SKIP_PROMPT_HISTORY 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 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 are stored under Claude Code’s temp directory rather than ~/.claude, so the purge doesn’t remove them. The retention sweep 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:
The plan lists each matching item and why it is included:
Delete with a single confirmation prompt:
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:
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 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. Don’t delete ~/.claude.json, ~/.claude/settings.json, or ~/.claude/plugins/: those hold your account details, preferences, and installed plugins.