BuildGist

Where Claude Code keeps session history, and how to get it back

Kayvan Zahiri ·

Claude Code saves each session as you work, per project folder. In that folder, claude --continue reopens the most recent session and claude --resume lets you pick one from a list. The transcripts are files under ~/.claude/projects/, kept for 30 days unless you change cleanupPeriodDays.

Get a session back

Claude Code's sessions documentation, read on October 16, 2026, gives these ways back in:

The picker starts with sessions from the current folder. Ctrl+A widens it to every project on the Mac, Space previews a session, and typing filters the list. Each row shows the session's name or a generated title, how long ago it was active, the Git branch and the file size.

A resumed session brings back the whole conversation, including tool calls and their results. Not everything from the original launch comes back: directories you added for that session, for one, have to be added again. The documentation lists the rest.

Name the sessions you will want again

Start a session with a name, claude -n auth-refactor, or name the one you are in with /rename auth-refactor. Then claude --resume auth-refactor opens it directly. A session you never name still gets a generated title, a short summary of your first prompt, and that title works with --resume too. A name is easier to remember a week later than a summary someone else wrote.

/clear does not delete the conversation

/clear starts a new, empty conversation. Claude Code keeps the one you left, and /resume finds it. In the same Claude Code process, the /rewind menu also offers a /resume (previous session) entry at the top of its list. /compact is different: it replaces the history in front of the agent with a summary, and you stay in the same session.

Where the files are

By default each session is one JSONL file:

~/.claude/projects/<project>/<session-id>.jsonl

The project part is the folder's path with each character that is not a letter or a digit replaced by -. Each line is one message, tool call or metadata entry.

The documentation says that format is internal to Claude Code and changes between versions, so a script that reads those files directly can break on any release. To read a session yourself, run /export in it. It copies the conversation to your clipboard or saves it as a plain-text file, with messages and tool output written out as readable text.

How long history is kept

Transcripts are kept for 30 days by default. To keep them longer, set cleanupPeriodDays in settings.json. CLAUDE_CONFIG_DIR moves the storage off ~/.claude, and claude purge deletes a project's transcripts and related state sooner.

The file snapshots that /rewind restores from are swept too, by default about 30 days after the session last saved one. An old session can resume and still fail to restore code. Undoing a run is in how to undo Claude Code changes.

What the history does not carry

The transcript stays in Claude Code. Cursor and Codex cannot open it, and a new Claude Code session does not see it unless you resume that session. Opened in the same folder, another agent reads the files the session changed, including uncommitted ones, but not the reasons. To move the task, write a short note or choose Continue on the BuildGist card. Both are in how to keep context across Claude Code, Cursor and Codex.

The conversation is also not a record of what changed in the code. A message can say a file was fixed when the fix landed in a different file, or never landed. For the code, read the working tree in the project folder:

git status
git diff --stat
git diff

A walk-through of those commands, including commits made during a run, is in what did Claude Code change?

A record of each run, from BuildGist

BuildGist explains each meaningful Claude Code, Cursor and Codex run in plain English, flags concerns, and puts the explanation in your Inbox. Each one says what changed, what it means and what to check, written from the run's changes, not from the chat. It works from uncommitted work too. Small changes stay quiet. It is written by AI, so check important behavior against the code and tests.

The Inbox is not a copy of the Claude Code conversation, and Claude Code's own history stays where it is. They answer different questions: the transcript is what was said, and the explanation is what the run did to your code.

Quick reference

What you need

Codex needs you to approve BuildGist once, in Codex. BuildGist shows the steps. Setup is in Getting started.

To explain a run, your computer sends BuildGist what that run needs, and BuildGist passes it to Anthropic. BuildGist does not keep this material. It does not send your whole repository, files the run did not change, or files named like secrets, such as .env files and keys. It keeps the explanation and short cited excerpts of changed code, at most 12 lines each. Secret masking is best-effort. Privacy has the full list.

Every account gets 7 days of BuildGist Pro free, with no card. The 7 days start at your first explanation or Continue handoff. Nobody is charged when the trial ends. After that, BuildGist Pro is $12 per month, plus any applicable tax shown at checkout. See pricing.

Try BuildGist

Apple silicon, macOS 12 or later. United States, 18 or older.

Related

Questions: kayvanandre@gmail.com.