skip to content

Where does Claude Code store session transcripts, how long does it keep them, and when do you use `/export` instead of reading the JSONL?

level: middleimportance: should knowfreq 9%

answer

  1. a file per session, per project
  2. under the user's config directory
  3. one JSON object per line
  4. retention sweep, default in days
  5. rendered text for people

basics

~10 s

Transcripts are JSONL files at ~/.claude/projects/<project>/<session-id>.jsonl, kept 30 days by default (cleanupPeriodDays). Their format is internal, so use /export for a readable plain-text copy and documented interfaces for scripts.

solid answer

~40 s

Claude Code writes each session continuously to `~/.claude/projects/<project>/<session-id>.jsonl`, where `<project>` is the working directory path with non-alphanumeric characters replaced by `-`. Each line is a JSON object for a message, tool use or metadata entry, and the format is internal and changes between versions, so parsers break. A background sweep deletes transcripts older than `cleanupPeriodDays`, 30 by default, silently, so old sessions vanish from the picker. They are plaintext: anything a tool read or printed, credentials included, is on disk. `/export` renders the conversation as plain text to the clipboard or a file for a person; scripts should use structured interfaces such as the `transcript_path` field in hook input or a JSON result from a non-interactive run.

go deeper

for a junior

Recall the path, ~/.claude/projects/<project>/<session-id>.jsonl, and that /export gives you a readable copy to share.

for a middle

Explain JSONL, how the project directory name is derived from the working path, and why scripts should use /export or documented fields like transcript_path instead of parsing lines.

for a senior

Treat transcripts as plaintext data with a 30-day default lifetime: tune cleanupPeriodDays, skip writes where secrets flow, and archive through a SessionEnd hook when records must outlive the sweep.

for a principal

Decide retention as policy: how long session records should exist for debugging and audit against how long plaintext tool output should sit on developer machines.

## Where the files live Claude Code saves each session as it goes, not at exit, to a **JSONL transcript**: `~/.claude/projects/<project>/<session-id>.jsonl` `<project>` is your working directory's path with every non-alphanumeric character replaced by `-`, so a session started in `/home/dev/my-app` lands under `~/.claude/projects/-home-dev-my-app/`. When the converted name would exceed 200 characters, it is truncated and a hash of the full path is appended. Next to the main file, a session directory holds related data, for example subagent transcripts under `<session>/subagents/` and large tool outputs under `<session>/tool-results/`. **JSONL** means one JSON object per line. Here each line is a message, a tool use or a metadata entry, so the file holds every prompt, every tool call and every tool result. ## Why scripts should not parse it The entry format is **internal to Claude Code and changes between versions**. A script that reads the lines directly works until an upgrade changes them. The documented alternatives: | Need | Use | | :- | :- | | A readable copy for a person, a ticket or a review | `/export` | | React when a session event happens | The `transcript_path` field that hooks and status line commands receive; a `SessionEnd` hook can archive the file | | A structured answer about an existing session | A non-interactive run that resumes it and returns JSON | | Messages inside your own application | The Agent SDK | Even `transcript_path` hands you the file's location, not a stable schema: copying or archiving the file is safe, interpreting its lines is the fragile part. ## `/export` `/export` renders the current conversation as **plain text**, with messages and tool outputs written as readable text. - With no argument it opens a menu to **copy to the clipboard** or **save to a file**. - With a filename, as in `/export flaky-test-notes.txt`, it writes straight to that file. It is meant for people: attaching a debugging session to an incident ticket, sharing how a fix was reached, or keeping a record of a design discussion after the transcript ages out. ## How long transcripts last A background sweep that runs after a session starts deletes transcripts older than `cleanupPeriodDays`: 1. The default is **30** days; the minimum is 1. 2. Setting `0` fails validation; for long retention pick a large number such as `3650`. 3. The sweep shows no message. A session older than the period simply stops appearing in the `/resume` picker, and its subagent transcripts go with it. ```json { "cleanupPeriodDays": 14 } ``` `CLAUDE_CONFIG_DIR` moves the whole storage root off `~/.claude`, and `CLAUDE_CODE_SKIP_PROMPT_HISTORY` set to `1` stops transcripts and prompt history being written at all; sessions started that way do not appear in `--resume` or `--continue`. ## Moving and addressing the files - `CLAUDE_CONFIG_DIR` moves the configuration directory off `~/.claude`, session history included, which suits a separate profile per client or a host that embeds Claude Code. - `CLAUDE_CODE_PROJECT_DIR_NAME`, set alongside `CLAUDE_CONFIG_DIR`, replaces the derived `<project>` name with one you choose; Claude Code ignores it when `CLAUDE_CONFIG_DIR` is unset, because a fixed name under the shared `~/.claude` would merge every project into one directory. - `claude --resume` accepts the absolute path of a `.jsonl` file in place of a session ID, which helps when you have the file but not the ID. ## Treat transcripts as sensitive Transcripts are **not encrypted at rest**; operating system file permissions are the only protection. If Claude reads a `.env` file or a command prints a token, that value is now in a `.jsonl` file under your home directory. Practical consequences: - Lower `cleanupPeriodDays` on machines that handle secrets. - Skip transcript writing for sessions that must leave nothing behind. - Review an `/export` before pasting it into a ticket, because it contains tool output too. ## Putting it together The transcript is what makes `claude -c`, `claude -r` and `/branch` possible: resume reads it back, and branching copies it. It is a working file for Claude Code, not an API. Read it through Claude Code's own commands and interfaces, export it when a person needs it, and decide its lifetime deliberately with `cleanupPeriodDays`.

  • How do you keep a copy of every session's transcript when it ends, without parsing it?
    Add a `SessionEnd` hook. Hooks receive a `transcript_path` field in their input, so the hook can copy that file to an archive location. Copying is safe across releases; interpreting the lines is what breaks, because the entry format is internal and changes between versions.
  • A command printed an API token during a Claude Code session. Where does it end up, and how do you limit exposure next time?
    In the session's `.jsonl` transcript under `~/.claude/projects/`, in plain text, protected only by file permissions, until the retention sweep deletes it. Lower `cleanupPeriodDays`, or set `CLAUDE_CODE_SKIP_PROMPT_HISTORY=1` for sessions that must not write transcripts at all.

A transcript is like an application's internal database file: you back it up and point tools at its location, but you query it through the application's own interface, because the table layout can change in the next release.

  • Transcripts are written only when the session exits cleanly
  • Transcripts are encrypted, so secrets in tool output are safe on disk
  • Setting cleanupPeriodDays to 0 keeps transcripts forever
  • The JSONL format is a stable API you can build tools against
  • /export produces the same JSONL file in a new location