Claude Code session files: what they hold, how big they get, whether to delete them

875 files and 1.6 GB on one laptop — and one of them was 586 MB

Every session your agent runs is written to disk as it happens. Claude Code puts JSONL under ~/.claude/projects, one directory per project and one file per session; Codex writes ~/.codex/sessions/**/rollout-*.jsonl; Cursor uses a SQLite database. Where each agent writes has the rest.

Nobody tells you these files exist until they are large.

How big they actually get

One developer's ~/.claude/projects: thirteen projects, two months of heavy daily use.

The distribution is the interesting part: a typical session costs a third of a megabyte, and a handful of runaway sessions carry most of the gigabytes. Growth is driven by tool output, not by how much you typed — a session that catted large files or ran a chatty build is orders of magnitude bigger than one where you talked through a design.

To find yours:

du -sh ~/.claude/projects
find ~/.claude/projects -name '*.jsonl' -size +50M

What is inside one

A Claude Code session file is JSON Lines: one JSON object per line, appended as the session runs. Each record carries a role, a timestamp, a session id and the payload — your prompt, the assistant's reply, or a tool call with its result. Codex, Copilot CLI and Antigravity use the same line-per-record shape with different field names; Cursor, Zed, Goose and Hermes use SQLite instead. The format registry documents each one field by field.

Two consequences worth knowing. It is plain text, so grep works and so does any tool you write. And it is verbatim: whatever scrolled past in your terminal is in there, including anything a command printed. Treat the directory as you would your shell history.

Claude Code deletes them for you

By default Claude Code keeps a transcript for 30 days and then removes it — the setting is cleanupPeriodDays in ~/.claude/settings.json, documented under data retention. Nothing announces it; people notice when --resume no longer lists a session they had in June. If you want the files to stay, raise the number before the month is up:

{ "cleanupPeriodDays": 3650 }

deja keeps what it indexed: a transcript the sweep removes stays searchable, because the index does not follow a single file out the door — only deja forget drops a session on purpose. The files themselves, though, are gone, and so is --resume for them.

The sweep is Claude Code's own, not a cron job, and it pauses whenever the client cannot safely determine the retention period — which is why the machine measured above, on the default setting, still holds 69 files older than 31 days. Do not read that as safety. The documented behaviour is deletion after 30 days, and the day the sweep runs is the day the June session goes.

Can you delete them yourself?

Yes — nothing in the agent breaks. What you lose:

• Resume. claude --resume lists sessions by reading these files. Delete one and it disappears from the list.
• Any history search, forever. Anything that answers "have I hit this before?" reads these files. Deleted transcripts are not recoverable and cannot be re-derived — the agent will not reconstruct them.
• Your own audit trail. It is the only record of what an agent actually ran in your repository. See auditing an agent.

If you need the space back, delete narrowly rather than emptying the directory:

# the few outliers, which is usually all the space you need
find ~/.claude/projects -name '*.jsonl' -size +100M -ls

# a project you will never open again
rm -rf ~/.claude/projects/-Users-you-old-project

Deleting by age is the tempting one and the one to avoid: old sessions are exactly the ones you no longer remember, so they are worth the most per byte.

Backing them up

They are ordinary files, so any backup tool works. If you want them readable somewhere else — a different machine, a different agent, or as Markdown — see exporting sessions and across machines.

Making them useful instead of just large

The files are already a complete record of every problem you have solved. What they lack is a way in: opening the right 300 KB file out of 875 is not a thing anyone does by hand.

curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto

deja builds a local index over those transcripts — every agent on the machine, including the sessions from before it was installed — and answers from them in milliseconds. Indexing a few gigabytes takes about ten seconds. Nothing is uploaded and credentials are stripped as the index is built (privacy). On the machine measured above the index is 204 MB against 1.6 GB of transcripts; what memory costs has the token side of it.

Does your agent remember previous conversations? · Finding a session · Getting started