Build1 publisher2 min readPublished
Claude Code sweeps agent transcripts older than 30 days off local disk by default
Claude Code deletes each local agent transcript once it is older than 30 days, the default for cleanupPeriodDays. Teams that keep sessions as design records need to raise the value or archive the files first, since only a backup restores a swept one.
The Engineer · Build desk
Drafted by a language model from the sources cited here and checked against its claim ledger before publication. How we use AISend a correction
What happened
- Claude Code writes each session to disk while it runs, as one JSONL file under ~/.claude/projects in a folder named after the working directory.
- According to the guide, the lowest value cleanupPeriodDays accepts is 1 day, and a value of 0 is rejected as invalid.
- Raising the value protects only transcripts still on disk; once one is swept, the only way to get it back is a home-folder backup such as Time Machine.
- A separate prompt log, ~/.claude/history.jsonl, keeps every typed prompt with its project and time, and the cleanup leaves it alone.
- The guide says the transcript format is internal to Claude Code and changes from one release to the next.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- decision A team that wants session records has to get a longer cleanupPeriodDays set on every machine that runs Claude Code, because the value sits in each user's home-directory settings file.
- cost Machines that ran on the default have already dropped sessions older than 30 days, so any record of earlier agent work now depends on what home-folder backups happened to capture.
- constraint Archive and search tooling built on the raw JSONL can break with a release, so a durable record needs /export output or a parser that someone keeps up to date.
A guide published on dev.to says the folder name comes from the working directory, with every non-alphanumeric character turned into a dash. A session started in /Users/you/code/api lands in ~/.claude/projects/-Users-you-code-api/ [2]. Inside that folder, each file is named by its session ID [1]. An archive can copy that layout and stay navigable by project.
Retention is one key in ~/.claude/settings.json [8]:
```json { "cleanupPeriodDays": 365 } ```
The guide's example is a year [8]. Zero looks like the natural way to write "never delete", and it fails validation [7].
The key lives in each user's home directory [8]. For a team, that makes retention a per-person, per-machine setting. An engineer who never edits the file loses sessions on the default schedule [6]. The guide covers only this user-level file and does not describe a project-level or shared retention setting.
The prompt log outlasts the sweep. The guide gives a one-liner to search it: `jq -r '.display' ~/.claude/history.jsonl | grep -Fi -- "migration"` [11]. That returns what you asked. The agent's replies and tool calls were stored in the per-session transcripts [3].
Archiving the raw files has its own catch. The guide advises readers to "treat it as something to read, not something to build on" [4]. Its own search script filters on type == "user" or "assistant", reads message.content and prints timestamp [13]. Those are internal field names, and the format changes between releases [4]. A year of archived transcripts can span more than one schema. A parser written against today's files has to cope with that.
Some of the design around the files is careful. If you pick a session from another project, Claude Code copies a cd and resume command to the clipboard instead of opening the session in the wrong directory [14]. The guide's search prints the session ID in its first column, and claude --resume with that ID reopens the session while it is still on disk [12].
In my context, an agent session is often the only written account of why a migration went one way. There, I would raise cleanupPeriodDays on day one and treat the higher value as a buffer. The actual record would be a copy outside ~/.claude, named by session ID, with /export output next to it. The guide says /export produces a readable copy of the current conversation [5].
What to watch
- Whether Claude Code documents a project-level or organisation-wide retention setting, so a team could set cleanupPeriodDays once for everyone.
- Schema changes to the session JSONL in a Claude Code release, the point at which jq-based search and archive scripts stop matching.
- Any change to the 30-day default for cleanupPeriodDays.