Where Claude Code stores conversations (and why they vanish)

TL;DR: Claude Code saves every conversation as a plain-text JSONL file at ~/.claude/projects/<project>/<session-id>.jsonl on your own machine (%USERPROFILE%\.claude\projects\ on Windows). By default it deletes those files after 30 days, silently. If you want to keep them, add "cleanupPeriodDays": 3650 to ~/.claude/settings.json today, then copy the projects/ folder somewhere that Claude Code never touches. Anything already deleted can only come back from a Time Machine or similar backup.

Where does Claude Code store conversations?#

Claude Code writes one file per session, in a folder named after the directory you started it in:

~/.claude/projects/<project>/<session-id>.jsonl

The sessions documentation gives the rule for <project>: take the full working directory path and replace every character that is not a letter or digit with -. <session-id> is a UUID, the same ID that claude --resume <session-id> accepts.

The Windows folder name is worked out from the documented rule (the colon and each backslash become a dash). I checked the macOS rows on my own machine.

A few details trip people up:

• Dots and underscores become dashes too. my.app, my_app and my-app all land in -Users-you-code-my-app. A git worktree under .claude/worktrees/feature shows up as …-my-app--claude-worktrees-feature, with a double dash where /. was.
• Long paths get a hash. If the converted name is longer than 200 characters, Claude Code cuts it to 200 and appends a hash of the full path.
• CLAUDE_CONFIG_DIR moves everything. Set it in your shell (for example CLAUDE_CONFIG_DIR=~/.claude-work claude) and settings, transcripts and plugins live under that folder instead. The environment variable reference notes that project-level settings files can't set it.

To open the newest session for the folder you're in on macOS or Linux:

ls -t ~/.claude/projects/$(pwd | sed 's/[^a-zA-Z0-9]/-/g')/*.jsonl | head -1

On Windows PowerShell, list the project folders with Get-ChildItem "$env:USERPROFILE\.claude\projects".

For the reading side (the /resume picker, /export, and viewers that render these files), see how to view Claude Code chat history. This post is about where the files are and how to stop losing them.

What else lives in ~/.claude#

The session file is only one of the things Claude Code writes. The .claude directory reference lists every path and whether the cleanup sweep removes it.

Two things live outside this folder. Per-project trust and MCP config sit in ~/.claude.json in your home directory. Images you paste are now saved under the system temp directory, not ~/.claude, and are deleted on the same schedule.

history.jsonl is worth knowing about when a transcript is gone: it survives the sweep, so your own prompts are still there, even though Claude's replies are not. Each line has display, pastedContents, timestamp and project keys.

What's inside a session file#

JSONL means "JSON Lines": one complete JSON object per line, appended as the session runs. You can read it with jq, grep, or any text editor.

Every conversation line carries the same envelope. Here is the shape of one assistant line from Claude Code 2.1.286, with the values removed:

{
  "type": "assistant",
  "uuid": "…", "parentUuid": "…", "sessionId": "…",
  "timestamp": "…", "cwd": "…", "gitBranch": "…", "version": "…",
  "isSidechain": false,
  "message": {
    "model": "…", "role": "assistant",
    "content": [{ "type": "thinking" }, { "type": "text" }, { "type": "tool_use" }],
    "usage": { "input_tokens": 0, "output_tokens": 0, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0 }
  }
}

• type: "user" lines hold what you typed (a plain string) or the result of a tool call (tool_result blocks), plus any images.
• type: "assistant" lines hold Claude's text, thinking and tool_use blocks, and the token counts for that response.
• Other types are bookkeeping. In one recent session I counted attachment, system, mode, last-prompt, queue-operation, file-history-snapshot and file-history-delta lines alongside the messages.
• parentUuid links each line to the one before it, which is how Claude Code rebuilds branches after /rewind.
• Sub-agent files have the same envelope with "isSidechain": true and an agentId.

To pull every prompt you typed out of one session:

jq -r 'select(.type=="user" and (.message.content|type)=="string") | .message.content' <session-id>.jsonl

Anthropic's docs are clear that this format is internal and "changes between versions, so scripts that parse these files directly can break on any release." For a stable interface, use /export, claude -p --resume <id> --output-format json, or the transcript_path field that hooks receive.

Why Claude Code history gets deleted after 30 days#

The setting is cleanupPeriodDays. According to the settings reference, checked on 1 October 2026:

• Default: 30 days. Minimum: 1.
• When: as a background sweep after a session starts. It deletes transcripts "without showing a message", so an old session simply stops appearing in /resume.
• What: everything marked "Yes" in the table above, including file-history. After the sweep, /rewind into that session can fail with "No files were restored" (checkpointing docs).
• Exception: since v2.1.248, sessions you started or last continued in Claude Desktop or Cowork are kept at any age unless you set desktopSessionCleanupPeriodDays.

This is the most common way people lose history. GitHub issue #62476, opened 26 May 2026 and still open, describes someone discovering that months of transcripts had gone while history.jsonl still listed 1,315 prompts from those sessions.

Don't set it to 0. Several older posts say 0 means "never delete". In older versions it actually stopped Claude Code writing transcripts at all (issue #23710). Current versions reject 0 with a validation error, and the docs recommend a large number instead.

There is no undo. Once a transcript is swept, Claude Code has no copy. The only way back is a file-level backup of your home folder (Time Machine, Windows File History, a snapshot of your Linux home), restored into the same projects/<project>/ folder.

How to keep your Claude Code history#

Do these in order. The first one takes a minute and stops further loss.

1. Raise the retention. Open ~/.claude/settings.json (create it if missing) and add:

   {
     "cleanupPeriodDays": 3650
   }

   Copy

   That's about ten years. If you already have other keys, add this line inside the existing braces. A value in a project's .claude/settings.json or in your organisation's managed settings overrides your user file, so if sessions keep disappearing, check those too.

2. Check it took. Run jq .cleanupPeriodDays ~/.claude/settings.json. If the settings file has a syntax error, Claude Code pauses the sweep and shows a warning in /status, which is safe but worth fixing.

3. Copy the transcripts somewhere else. The setting protects against Claude Code's own sweep, not against a reinstall, a new laptop, or claude project purge. A plain copy is enough:

   rsync -a ~/.claude/projects/ ~/Backups/claude-projects/

   Copy

   Run it from cron or launchd, or make it a SessionEnd hook. Hooks get the session's transcript_path, and the docs mention archiving the transcript as a use for SessionEnd. SessionEnd hooks get a 1.5-second budget by default, so keep the copy small or raise the hook's timeout.

4. Keep it out of git. If you version your dotfiles, add these to that repo's .gitignore:

   .claude/projects/
   .claude/history.jsonl
   .claude/file-history/
   .claude/paste-cache/

   Copy

   These files hold whatever passed through a tool, including .env contents and command output, so a public dotfiles repo is the wrong place for them.

For scale: on my machine, with cleanupPeriodDays at 90, ~/.claude/projects held 42 project folders, 753 session files and 1,622 JSONL files including sub-agent transcripts, 1.5 GB in total, on 1 October 2026. find ~/.claude/projects -name '*.jsonl' -mtime +90 returned nothing, which is the sweep doing its job.

If you mainly want to know what those sessions cost before they're deleted, the usage tracker post covers that side.

Is anything uploaded? Privacy and local files#

Two separate things happen to your conversation.

On your disk. Transcripts and history.jsonl are plaintext and not encrypted at rest; file permissions are the only protection (plaintext storage). If Claude reads a .env file, its contents are in the transcript. To write less:

• lower cleanupPeriodDays
• set CLAUDE_CODE_SKIP_PROMPT_HISTORY to stop writing transcripts and prompt history
• pass --no-session-persistence for a single claude -p run
• run claude project purge <path> to delete one project's transcripts, memory, file history and matching history.jsonl lines. --dry-run shows the plan first.

On Anthropic's servers. To run the model, Claude Code sends your prompts and the model's outputs to Anthropic over TLS. How long Anthropic keeps them depends on your account (data usage docs):

The local .jsonl files themselves are not synced. A transcript file is uploaded only when you send one: via /feedback (kept 5 years), or by answering Yes to the "Can Anthropic look at your session transcript?" survey follow-up (kept up to 6 months). A Remote Control session also stores its transcript on Anthropic's servers while connected, so you can continue it on another device.

Where CCAssist fits#

CCAssist is a VS Code extension that reads these same ~/.claude/projects files (and Codex CLI's) locally and shows them as a searchable history with diffs. It doesn't change what Claude Code stores or deletes. If you use CLAUDE_CONFIG_DIR, point the claude-history.claudeDirectory setting at that folder, because the extension looks in ~/.claude by default.

For the cleanup problem specifically:

• Archive a session (right-click it and choose Archive Session) to copy its JSONL to ~/.ccassist/archives/ (configurable with claude-history.archiveDirectory), a folder Claude Code's sweep never touches. When Claude Code later deletes the original, the session stays viewable in the Archived tab, and Resume copies it back to ~/.claude/projects/ so claude --resume finds it. A Sync button refreshes archives with messages added since. Free covers 3 archived sessions; Pro removes the limit. Viewing and restoring archives is free.
• Export to Markdown for a portable copy you can commit. Free covers 3 sessions.

What it does not do: it doesn't back up sessions automatically, and it can't bring back a transcript Claude Code deleted before you archived it. It only has what's on disk or in its archive folder. Set cleanupPeriodDays first; archiving is for the sessions you want to keep regardless.

To compare it with other tools for browsing history, see the best Claude Code VS Code extensions for 2026.

How we checked#

• Claude Code version: 2.1.286 on macOS, 1 October 2026.
• Docs read on 1 October 2026: sessions, .claude directory, settings reference, environment variables, checkpointing, hooks, data usage.
• Local data: folder names, file counts, sizes and JSONL key names only. No prompt text or project content is quoted; the example project is -Users-you-code-my-app.
• CCAssist: features checked against the extension source and changelog for version 0.7.5, the Marketplace release on 1 October 2026.
• Not verified: the Windows and WSL rows were not run on those systems; they follow the documented naming rule.

Install CCAssist from the VS Code Marketplace and your ~/.claude/projects sessions appear as a searchable, per-project history list in the sidebar, with Archive Session in each one's right-click menu.