Claude Code · settings

How to use cleanupPeriodDays to keep Claude Code history

Short answer: cleanupPeriodDays is the number of days Claude Code keeps session transcripts before deleting them. The default is 30. Set it higher in ~/.claude/settings.json:

{
  "cleanupPeriodDays": 36500
}

Where to set it

The setting can go in any settings file: your user file ~/.claude/settings.json, a project's .claude/settings.json, its .claude/settings.local.json, or the managed settings your organisation deploys. For your own history, the user file is the one to use. (Settings reference)

Managed settings matter here: when they set cleanupPeriodDays, Claude Desktop and Cowork sessions follow it too, instead of being kept at any age.

Values

Default: 30 days.
Minimum: 1. Setting 0 fails with a validation error.
Large values such as 36500 keep transcripts for practical purposes indefinitely.
desktopSessionCleanupPeriodDays sets a separate age limit for sessions started or last continued in Claude Desktop or Cowork (Claude Code v2.1.248 or later; user or managed settings).

Check it's working

If Claude Code can't safely work out the retention period, for example because a settings file can't be parsed, it pauses the sweep, and when cleanupPeriodDays is explicitly set it shows a warning in /status until you fix it. Organisations can watch the retention_sweep event.

What it doesn't do

It keeps nothing extra. It only delays deletion of the one copy in ~/.claude. Users have reported losing sessions despite a high setting (#62272).
It doesn't keep file versions. Snapshots of files Claude changed are held for the 100 most recent checkpoints only.
It doesn't search or fingerprint anything.

Belt and braces: an archive

Rootz Archive keeps its own exact copy of every Claude Code conversation and every file Claude edits on your computer, fingerprinted with SHA-256, whatever cleanupPeriodDays says, and your AI can search it. Free for individual users; nothing is sent to Rootz.

claude plugin marketplace add rootz-global/rootz-archive
claude plugin install rootz-archive@rootz

Then type /rootz-archive:accept in a new Claude Code session.

Questions

What is the default value of cleanupPeriodDays?

30 days. The minimum is 1; 0 is rejected with a validation error.

Does cleanupPeriodDays apply to Claude Desktop sessions?

Not by default since Claude Code v2.1.248: sessions started or last continued in Claude Desktop or Cowork are kept at any age unless you set desktopSessionCleanupPeriodDays, or managed settings set cleanupPeriodDays.

Is a high cleanupPeriodDays a backup?

No. It only delays deletion of the single copy Claude Code keeps. Keep your own backups, or an archive that keeps a separate copy.

Keep what actually happened. What Claude Code deletes, and when · Rootz Archive

Facts from Anthropic's documentation as of October 2026. Written with Claude, reviewed by Rootz.