AI Coding Guide

When Claude Code deletes transcripts: the cleanupPeriodDays default and how to change retention

Claude Code Published:

Claude Code stores transcripts in plain text under ~/.claude. What cleanupPeriodDays does (default 30 days, minimum 1), what the sweep deletes and skips, and how to stop writing.

Verified on Sep 10, 2026 These tools change quickly. Please also check the latest official documentation.
#Claude Code#cleanupPeriodDays#transcripts#privacy#settings.json
Contents
  1. How cleanupPeriodDays works
  2. What gets deleted and what does not
  3. Not writing transcripts at all
  4. Purging one project
  5. Summary

Claude Code writes the whole conversation, every message, tool call, and tool result, to ~/.claude/projects/<project>/<session>.jsonl in plain text. If a tool reads .env, its contents land there. If a command prints a token, so does the token.

In short: retention is controlled by cleanupPeriodDays in settings.json, with a default of 30 days. You can shorten it to reduce exposure, and there are ways to stop writing transcripts altogether.

KEY POINT

What you will learn

  • The default and minimum for cleanupPeriodDays, and why 0 is rejected
  • Which files the sweep deletes and which it leaves alone
  • How to stop transcripts being written, and how to purge one project

How cleanupPeriodDays works

ItemValue
Default30 days
Typewhole number, minimum 1
Setting 0fails validation
Whereany settings file; the highest-priority layer that sets it wins
When it runsa background sweep after a session starts
{
  "cleanupPeriodDays": 7
}

There is no "never delete" value. For long retention, use a large number such as 3650.

用語解説

Retention sweep: the background deletion that runs after a session starts. If Claude Code cannot safely determine the retention period, for instance because a settings file cannot be read or parsed, it pauses the sweep, and shows a warning in /status when the broken settings explicitly set cleanupPeriodDays. When managed settings provide the value, the sweep runs at that value regardless.

What gets deleted and what does not

Paths removed once they are older than cleanupPeriodDays:

Under ~/.claude/Contents
projects/<project>/<session>.jsonlthe full conversation transcript
projects/<project>/<session>/subagents/subagent transcripts, removed with the parent
feedback/drafts/queued /feedback drafts, after cleanupPeriodDays or 30 days, whichever is shorter
todos/, statsig/, logs/legacy directories; contents and then the empty directory are removed

Not covered by the sweep:

  • history.jsonl: every prompt you typed, used for up-arrow recall and Ctrl+R; kept until you delete it
  • auto memory: projects/<project>/memory/ is not deleted; the directory goes only if it stayed empty for the whole period
  • Claude Desktop and Cowork sessions: kept at any age by default; desktopSessionCleanupPeriodDays adds a limit (v2.1.248 or later)
  • stats-cache.json: the aggregates shown by /usage

desktopSessionCleanupPeriodDays deletes a transcript only when it is older than both that value and cleanupPeriodDays, so with the default 30 a value of 7 still keeps them 30 days.

Not writing transcripts at all

Beyond shortening retention, you can stop the recording itself.

CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 claude

The .claude directory page says this variable skips writing transcripts and prompt history in any mode. The environment variables page describes it as disabling loading of prompt history from disk, so the two descriptions differ. In non-interactive mode you can instead pass --no-session-persistence alongside -p.

Bare mode, -p with --bare, does not run the sweep in that session at all.

Keep credentials out in the first place

A short retention period still leaves plain-text files on disk until they age out. Deny reads of .env and key files before relying on retention. The rules are covered in Keeping secrets away from AI coding tools.

Purging one project

claude project purge deletes the state Claude Code holds for a single project in one go. Data use for training is a separate question from local retention; local context management in general is covered in Managing context in Claude Code.

Summary

  • Transcripts are stored in plain text under ~/.claude/projects/ and deleted after cleanupPeriodDays (default 30, minimum 1)
  • 0 is rejected; use a large value such as 3650 for long retention
  • history.jsonl, auto memory, and Desktop/Cowork sessions are outside the sweep; Desktop gets its own key
  • CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 stops writing; --no-session-persistence does the same for -p
  • Deny credential reads up front, and use claude project purge to wipe one project

FAQ

Can I set cleanupPeriodDays to 0 to keep transcripts forever?
No. 0 fails validation. Use a large value such as 3650 for long retention. The minimum is 1.
Are transcripts encrypted?
No. OS file permissions are the only protection. A .env a tool read, or a credential a command printed, is stored as is.
When does deletion run?
As a background sweep after a session starts. A settings error that prevents determining the retention period pauses the sweep.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles