Part of the AI coding agent security checklist

Claude Code cleanupPeriodDays: how long your history is kept

You go back for last month's session and /resume no longer lists it. Claude Code deleted it: after 30 days, by default, a background sweep removes every older transcript without a message. cleanupPeriodDays is the setting that decides that, and it has a few traps.

$ uvx ranwhat check --days 365
Install

Checked against Claude Code's settings reference and .claude directory documentation under Sources. Published .

01 / What

What does cleanupPeriodDays do in Claude Code?

It sets how many days Claude Code keeps each session's transcript before deleting it: 30 by default.

Value A whole number of days, minimum 1.
Files The transcripts in ~/.claude/projects/<project>/<session-id>.jsonl: every message, tool call and tool result of a session.
When A background sweep after a session starts. It deletes anything older than the period, without a message, so an old session just stops appearing in /resume.
Paused If Claude Code cannot work out the period, for example because a settings file cannot be read or parsed, it pauses the sweep rather than guess, and /status shows a warning. Runs with claude -p --bare skip the sweep.
02 / Longer

How do I keep Claude Code history longer than 30 days?

Set cleanupPeriodDays in ~/.claude/settings.json to a larger number.

~/.claude/settings.json
{
  "cleanupPeriodDays": 365
}
Long Claude Code's documentation suggests something like 3650 for long retention.
Not back A higher value keeps what the sweep has not reached yet. It does not bring back sessions already deleted, so set it before you need the record.
Managed Managed settings, where an organisation sets them, take precedence over your own file.
Shorter A smaller number means less sitting on disk. The documentation lists lowering it as a way to reduce exposure, since the transcripts are plaintext and hold whatever the session saw.
03 / Zero

Can I set cleanupPeriodDays to 0?

No. 0 fails validation: it means neither keep nothing nor keep forever.

To stop transcripts being written at all, start Claude Code with CLAUDE_CODE_SKIP_PROMPT_HISTORY=1: those sessions write no transcript and no prompt history, and do not appear in --resume. For one claude -p run, --no-session-persistence skips the transcript.

CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 claude
claude -p --no-session-persistence "run the tests"
04 / Kept

What does the cleanupPeriodDays sweep not delete?

~/.claude/history.jsonl and stats-cache.json are never swept, so every prompt you typed stays.

Prompts history.jsonl holds each prompt with a timestamp and the project path, for up-arrow recall. It stays until you delete it.
Desktop From Claude Code v2.1.248, transcripts of sessions you started or last continued in Claude Desktop or Cowork are kept at any age, unless you set desktopSessionCleanupPeriodDays. Each is then deleted once it is older than both limits. If managed settings set cleanupPeriodDays, that period applies to them instead.
Scratch A purged session's scratchpad in the temp directory stays until you or the operating system clear it. The history guide lists the rest.
05 / Before

How do I see what is in my Claude Code history before it is deleted?

Run uvx ranwhat check: it reads the transcripts still on disk and changes nothing.

It lists the risky actions the agent took and the credentials left in the transcripts. Its --days window is 30 by default, the same as Claude Code's default retention. If you raised cleanupPeriodDays, widen it to match: uvx ranwhat check --days 365. To keep a record that does not depend on the sweep at all, add a hook or OpenTelemetry, as the Claude Code audit log guide shows.

06 / Others

Do Gemini CLI, Codex and Cursor have a cleanupPeriodDays?

Gemini CLI has one; Codex and Cursor document no retention period for sessions.

Claude Code cleanupPeriodDays, 30 days by default.
Gemini CLI general.sessionRetention in settings.json: maxAge defaults to "30d", with maxCount and minRetention.
Codex None documented for the rollout files. history.max_bytes caps history.jsonl. Codex session history.
Cursor None documented. Chats stay in its database until you delete them in Cursor. Cursor chat history.

Every agent's path and setting is in where AI coding agents keep history.

07 / Questions

Common questions about cleanupPeriodDays

What is the default cleanupPeriodDays in Claude Code?

30 days. Transcripts older than that are deleted by a background sweep after a session starts, without a message.

Where do I set cleanupPeriodDays?

In ~/.claude/settings.json, as "cleanupPeriodDays": 365 or any whole number from 1. Managed settings, where an organisation uses them, take precedence.

Does raising cleanupPeriodDays restore deleted sessions?

No. It only keeps what the sweep has not deleted yet. A session older than the old period is already gone.

Is keeping Claude Code history longer a risk?

It is a trade. The transcripts are plaintext, protected only by file permissions, and hold whatever the sessions read, secrets included. A longer period is a longer audit record and more for anything running as you to read. Check them with uvx ranwhat check either way.