The .claude folder, explained, and what Claude Code stores

Claude Code reads its instructions, settings, skills, subagents and memory from two places: a .claude folder in your project and a .claude folder in your home directory. It also writes files there as you work. Knowing which is which tells you what to edit, what to commit and what to clean up.

Two folders, two jobs

• In your project: shared setup. Commit these files to git and your team gets them too.
• In your home directory (~/.claude): your personal setup, across all projects. On Windows that is %USERPROFILE%\.claude.

Most people only ever edit CLAUDE.md and settings.json. The rest is optional: add it when you need it. If your repository already has an AGENTS.md written for other coding agents, Claude Code can read that in place of a CLAUDE.md.

The files you write

• CLAUDE.mdInstructions loaded every session. Project or global. Commit the project one.
• CLAUDE.local.mdYour private preferences for one project, loaded next to CLAUDE.md. You create it yourself and add it to .gitignore.
• rules/*.mdInstructions split by topic, optionally limited to certain paths.
• settings.jsonPermissions, hooks, environment variables and model defaults. Commit the project one.
• settings.local.jsonYour personal overrides for one project. Not meant for git.
• .mcp.jsonMCP servers shared with the team. Project only. Sits at the project root, not inside .claude.
• skills/<name>/SKILL.mdReusable prompts you call with /name, or that Claude picks up by itself.
• commands/*.mdSingle-file prompts. Same mechanism as skills.
• agents/*.mdSubagents, each with its own prompt and tools.
• output-styles/*.mdCustom instruction sets that change how Claude responds.
• ~/.claude.jsonApp state, account details and personal MCP servers. Global only. Not for git.
• keybindings.jsonYour keyboard shortcuts. Global only.

Not sure where a change belongs? Allow or block a tool: settings.json permissions or a hook. Run a script around tool calls: a hook. Keep personal overrides out of git: settings.local.json. A prompt you call with /name: a skill. Settings from different files can clash, so see which settings file wins. For the choice between instructions, skills and hooks, see CLAUDE.md, skill, hook or subagent.

What Claude Code writes while you work

Besides what you author, ~/.claude fills up with files Claude Code creates:

• Transcripts in projects/<project>/: the messages, tool calls and tool results of each session, plus the system prompt, tool definitions and the instruction files it loaded.
• Snapshots in file-history/: copies of files before Claude edited them, used by /rewind. They cover the 100 most recent checkpoints.
• Plans from plan mode, large pastes, debug logs (only while debug logging is on) and other working files.
• Prompt history in history.jsonl: the prompts you typed, with a timestamp and project path.
• Auto memory in projects/<project>/memory/: Claude's notes to itself across sessions.

The part to read twice: it is plaintext

The documentation says transcripts and history are not encrypted at rest, and that file permissions on your computer are the only protection. If a tool reads a .env file or a command prints a credential, that value is written into the session transcript. So it is worth thinking about who can read that folder, and about backups that copy it.

How long things stay

• Most of the working files (transcripts, snapshots, plans, debug logs, pastes) are deleted automatically once they are older than cleanupPeriodDays. The default is 30 days, and the minimum is 1. Setting 0 is rejected.
• Some files are kept until you delete them, including history.jsonl and the usage statistics cache.
• Auto memory files are not swept away by that cleanup.
• Running claude -p with --bare skips the age-based cleanup for that session.

Reduce what is stored

• Lower cleanupPeriodDays to keep transcripts for fewer days.
• Set the CLAUDE_CODE_SKIP_PROMPT_HISTORY environment variable to skip writing transcripts and prompt history. In non-interactive runs, --no-session-persistence alongside -p does the same job. See run Claude Code from a script.
• Deny reads of credential files with a permission rule. See a starter list of permission rules.
• To wipe what Claude Code holds for one project, use claude purge. It deletes that project's transcripts, auto memory, per-session task, debug and snapshot entries, the matching prompt lines in the history and the project's entry in ~/.claude.json. It prints the full plan and asks you to confirm first, and --dry-run shows the plan without deleting anything. Older versions called it claude project purge.

Do not delete these

Caches and lock files are safe to remove. Keep .credentials.json (your login), agent-memory/ (subagent memory) and the jobs/ and daemon/ folders (state of background sessions).

Try it on something harmless

1. Open your ~/.claude folder and look at the names. Do not open anything you would not want on screen.
2. Find settings.json in a project's .claude folder and check whether it is committed to git.
3. Run claude purge <path to a test project> --dry-run and read the plan. It deletes nothing.

Limits

• File names, locations and retention rules change between versions, and some details need a minimum version. The documentation page is the authority.
• This is general information about a tool, not privacy or legal advice.

This follows Anthropic's documentation of the .claude directory as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.