# Claude Code cleanupPeriodDays: how long your history is kept

> cleanupPeriodDays is how many days Claude Code keeps session transcripts: 30 by default, minimum 1. How to raise it, why 0 fails, and what the sweep never deletes.

Canonical: https://ranwhat.com/guides/claude-code-cleanupperioddays
Last updated: 2026-11-16

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](https://ranwhat.com/install)

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

## 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.

## 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.

## 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"
```

## 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](https://ranwhat.com/guides/claude-code-history) lists the rest.

## 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](https://ranwhat.com/guides/claude-code-audit-log) shows.

## 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](https://ranwhat.com/guides/codex-cli-session-history).
- **Cursor**: None documented. Chats stay in its database until you delete them in Cursor. [Cursor chat history](https://ranwhat.com/guides/cursor-chat-history).

Every agent's path and setting is in [where AI coding agents keep history](https://ranwhat.com/guides/ai-coding-agent-history-locations).

## 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.

## Sources

- [Settings referencecleanupPeriodDays, desktopSessionCleanupPeriodDays](https://code.claude.com/docs/en/settings-reference#cleanupperioddays)
- [Explore the .claude directorywhat is swept, what is kept, plaintext storage](https://code.claude.com/docs/en/claude-directory#application-data)
- [Environment variablesCLAUDE_CODE_SKIP_PROMPT_HISTORY](https://code.claude.com/docs/en/env-vars)
- [Gemini CLI session managementgeneral.sessionRetention](https://geminicli.com/docs/cli/session-management/)

## Related guides

- [Claude Code historywhere the transcripts are and how to view them](https://ranwhat.com/guides/claude-code-history)
- [Claude Code audit logthe transcripts as a record of what ran](https://ranwhat.com/guides/claude-code-audit-log)
- [AI coding agent security checklistevery other control, in order](https://ranwhat.com/guides/ai-coding-agent-security)
- [All guideseverything in this section](https://ranwhat.com/guides)
