What is inside the ~/.claude folder

Start with du -sh ~/.claude/* to see what is using disk space. This directory contains configuration, plugin files and retained session history. Back up anything you need before deleting it: custom instructions and plugin data may not be recoverable by reinstalling Claude Code.

By Miguel Silva · Updated 2026-09-12

What each thing in ~/.claude is for

~/.claude/skills/

Your personal skills, one folder per skill with a SKILL.md inside. Available in every project on the machine.

~/.claude/agents/

Your personal subagents. One markdown file each, whose frontmatter carries the name and the description that decides when the agent is picked.

~/.claude/commands/

Your custom slash commands. One markdown file per command, and the file name is the command you type.

~/.claude/plugins/

Installed plugins, with the skills, subagents and commands they brought with them. Not written by you, and restorable by reinstalling.

~/.claude/projects/

Session transcripts, one folder per project directory you have worked in. This is what --continue and --resume read, and the only record of what you actually used.

~/.claude/settings.json

Your settings: granted permissions, environment variables, hooks, model choice. The file that decides what Claude may do without asking.

~/.claude/CLAUDE.md

Your global instructions, loaded into every session in every project, on top of whatever CLAUDE.md the project itself has.

The split worth holding on to: the first four are things you install, the next is history, and the last two are how you have configured the tool. They fail in different ways, so they are worth treating differently.

Why the folder is so large

Almost always projects. Skills, agents and commands are small text files; transcripts are a line of JSON per message, kept for every session, and they accumulate faster than anything else here. Something does prune them; Claude Code sweeps transcripts older than cleanupPeriodDays, which defaults to 30 days; but the sweep has holes worth knowing about, and it pauses entirely if it cannot read your settings.

du -sh ~/.claude/*              # totals per entry, biggest offender usually projects
ls ~/.claude/projects           # one folder per project path you have worked in

The project folder names are the project path with the slashes turned into dashes, which is why a repository you deleted months ago still has a folder here.

What Claude Code already deletes for you

Before deleting anything by hand, it is worth knowing what is already on a timer. Claude Code runs a retention sweep over roughly seventeen paths under ~/.claude, removing what is older than cleanupPeriodDays. The default is 30 days, the minimum is 1, and setting it to 0 fails with a validation error rather than disabling the sweep.

projects/<project>/<session>.jsonl

The full transcript of a session: every message, tool call and tool result. Subagent transcripts and any large tool outputs spilled to tool-results/ age out with their parent.

file-history/<session>/

Pre-edit snapshots used for checkpoint restore, capped at the 100 most recent checkpoints. Usually the second-largest thing here after projects.

paste-cache/, image-cache/, uploads/

Large pastes, attached images and files attached from the web or mobile app. On each sweep the image cache also drops every other session’s directory whatever its age.

plans/, debug/, tasks/, shell-snapshots/, usage-data/, session-env/, backups/

Plan-mode files, debug logs written only under --debug, task lists, startup shell state, /insights reports, per-session environment metadata, and rotating copies of ~/.claude.json (the five newest are kept).

Four things escape the sweep, and they are the reason a folder can stay large after the timer should have shrunk it. The sessions/ directory is cleared per session rather than by age. A project’s auto memory at projects/<project>/memory/ is excluded on purpose. Bare mode; claude -p with --bare; does not run the sweep at all in that session. And if Claude Code cannot safely determine the retention period, it pauses the sweep entirely: a settings file it cannot parse will quietly stop the cleanup and show a warning in /status until you fix it.

Purging one project, without touching the rest

The blunt version of reclaiming space is to delete a folder under projects/. The safe version is claude project purge, which takes one project and removes everything Claude Code holds for it; the transcripts and auto memory, the per-session tasks, debug and file-history entries, the matching prompt lines in history.jsonl, and the project’s entry in ~/.claude.json, which is where its trust decision and its MCP servers live.

claude project purge ~/work/my-repo --dry-run   # print the plan, delete nothing
claude project purge ~/work/my-repo             # same plan, then one y/N prompt
claude project purge ~/work/my-repo --yes       # no prompt, for scripts
claude project purge --all                      # every project at once

The dry run names each item and why it is included, and it tells you what it is leaving alone: shell-snapshots/ is not project-scoped, and old copies of ~/.claude.json under backups/ may still carry the project entry until they rotate out. Omit the path and it offers an interactive list; pass --all and history.jsonl is deleted outright rather than filtered. It is the one deletion here with a preview, which is a good reason to prefer it to rm.

What is safe to delete, and what is not

• projects: deleting it removes retained transcripts and can prevent resuming sessions. Aggregate counters in ~/.claude.json are separate; they cannot reconstruct deleted conversation history.
• settings.json: deleting it resets Claude Code to defaults. Nothing breaks permanently, but every permission you granted has to be granted again, and any hooks you configured stop firing silently.
• CLAUDE.md: deleting it removes your standing instructions from every future session. Sessions still run; they just stop behaving the way you taught them to.
• skills, agents, commands: deleting them removes your custom capabilities. Preserve a backup or version-controlled copy before deleting your own work.
• plugins: use the plugin uninstall command instead of deleting the entire directory. Persistent plugin data may be lost; preserve it with --keep-data when needed.

The order that follows from this: prune projects if you need space, and read what is in skills, agents and commands before removing any of it. A folder you do not recognise is more often something you installed and forgot than something that does not matter.

The .claude folder in a project is a different thing

A repository can have its own .claude folder, and it holds the same kinds of things (skills, agents, commands, settings) scoped to that project and committed with it. It is not a copy of the home one, and the two are loaded together.

~/.claude/

Yours. Applies in every project on this machine, and travels with the machine, not the code.

.claude/ (in a repository)

The project’s. Applies only inside it, and arrives with a clone for everyone on the team.

For skills, enterprise overrides personal, and personal overrides project. Settings and other configuration types have their own precedence rules; do not apply the skill rule to the whole directory.

Questions

Can I delete the ~/.claude folder?

You can, and Claude Code will recreate what it needs on the next run, but you lose all session history, every granted permission, your global CLAUDE.md and anything you wrote in skills, agents or commands. Delete individual entries instead, and leave projects for last.

What is taking up all the space in ~/.claude?

Run du -sh ~/.claude/* to measure your setup. Transcripts and plugin caches can both be large. Claude Code cleans eligible history according to cleanupPeriodDays, normally 30 days; some files have separate retention rules.

Is ~/.claude the same as ~/.claude.json?

No. ~/.claude is the folder holding your skills, plugins, history and settings.json. ~/.claude.json is a separate file next to it in your home directory, and the two are not interchangeable when you are following instructions that name one of them.