# Where Codex CLI keeps your session history

> Codex keeps every thread as JSONL in ~/.codex/sessions, by day, with no retention documented. What each file holds, the shell snapshots, and how to cap it.

Canonical: https://ranwhat.com/guides/codex-cli-session-history
Last updated: 2026-11-16

Claude Code deletes its transcripts after 30 days by default. Codex documents no such limit for its sessions, so every thread you have run since you installed it can still be in `~/.codex`, with each command's output. Where the files are, what they hold, and how to cap them.

```
$ uvx ranwhat check --source codex
```

[Install](https://ranwhat.com/install)

Paths are the ones ranwhat's Codex reader uses, checked against Codex rust-v0.159.3 and its configuration documentation under Sources. Published 16 November 2026.

## Where does Codex store session history?

In `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, one file per thread, or under `$CODEX_HOME` if you set it.

- **Threads**: `sessions/YYYY/MM/DD/rollout-*.jsonl`. The CLI, the IDE extension and the desktop app all write here. On Windows, `~` is `%USERPROFILE%`.
- **Compressed**: `rollout-*.jsonl.zst` once a thread has been idle for a week.
- **Archived**: `archived_sessions/rollout-*`, a flat folder.
- **Prompts**: `history.jsonl`: the prompts you typed.
- **Shell**: `shell_snapshots/*.sh` and `*.ps1`: your shell's exported variables.
- **Index**: `thread_history_1.sqlite` and `state_5.sqlite`, in `sqlite_home` from `config.toml`, else `$CODEX_SQLITE_HOME`, else `CODEX_HOME`.
- **Older**: Early Rust builds wrote a flat `sessions/rollout-*.jsonl`; the TypeScript CLI wrote one JSON document per thread, `rollout-*.json`.

## What is in a Codex rollout file?

The whole thread: each line is one JSON event with a `timestamp`, a `type` and a `payload`.

- **Calls**: Every tool call, such as a shell command or a patch, and its output, in `response_item` lines.
- **Your commands**: A command you ran yourself with `!` is recorded as a user message holding the command, its exit code and its output.
- **Forks**: A forked thread or a subagent can start with a copy of its parent's history, written with the time of the copy, so the same call can appear in two files.
- **Secrets**: Whatever a command printed or a file read showed is in the output, a credential included. `shell_snapshots/` can hold any token you exported in that shell.

## Does Codex delete old sessions?

Not by any documented rule: the docs give no retention period for the rollout files.

The configuration documentation names `[history] persistence = "none"` in `config.toml` to stop saving history, and `history.max_bytes` to cap it. It does not say whether the rollouts under `sessions/` follow it, so check the folder after a new session.

```
$ ~/.codex/config.toml
[history]
persistence = "none"
```

For comparison: Claude Code's [cleanupPeriodDays](https://ranwhat.com/guides/claude-code-cleanupperioddays) defaults to 30 days, and Gemini CLI's `general.sessionRetention` to `"30d"`.

## How much Codex history do I have?

`du -sh ~/.codex/sessions` gives the total; `ls ~/.codex/sessions` shows the years it covers.

```
du -sh ~/.codex/sessions ~/.codex/archived_sessions ~/.codex/history.jsonl
ls ~/.codex/sessions
ls ~/.codex/shell_snapshots | wc -l
```

## How do I check what Codex ran and which secrets it kept?

Run `uvx ranwhat check --source codex`: it reads the rollouts, flags risky calls and finds credentials, changing nothing.

- **watch**: `uvx ranwhat watch --source codex` lists what Codex ran, rated by its rules. Widen the window with `--days 365`, since Codex keeps far more than 30 days.
- **clean**: `uvx ranwhat clean --source codex` lists credentials in the rollouts, `history.jsonl` and the shell snapshots, and with `--apply` masks them after a backup.
- **zst**: Compressed rollouts are read when a zstd decoder is available, and never rewritten.
- **Never**: `auth.json` and Codex's logs are never opened.

## How do I delete Codex session history?

Remove the files: there is no purge command, and deleting them only removes your local copy.

Delete a day's folder under `sessions/`, `archived_sessions/` or `history.jsonl` when Codex is not running. If a thread showed a credential, rotate it first: the copy was readable for as long as it sat there. [Rotate a leaked key](https://ranwhat.com/guides/rotate-leaked-api-key-ai-agent) has each provider's steps.

## Common questions about Codex history

### Where is Codex CLI history stored?

In `~/.codex/sessions/YYYY/MM/DD/`, one `rollout-*.jsonl` file per thread, plus typed prompts in `~/.codex/history.jsonl`. Set `CODEX_HOME` and it all moves there.

### What is ~/.codex/history.jsonl?

The prompts you typed into Codex. `history.max_bytes` in `config.toml` caps its size.

### Why are some Codex sessions .jsonl.zst files?

Codex compresses a thread with zstd once it has been idle for a week. `zstd -dc` prints one.

### Does Codex keep secrets in its history?

It keeps whatever a session saw: a printed key, a file it read, and the exported variables in its shell snapshots. `uvx ranwhat clean --source codex` finds them.

## Sources

- [Codex advanced configurationhistory.persistence, history.max_bytes, CODEX_HOME](https://learn.chatgpt.com/docs/config-file/config-advanced)
- [ranwhat source: codex.pythe store layout, line types and what is never opened](https://github.com/MatijaMiki/ranwhat/blob/main/ranwhat/sources/codex.py)

## Related guides

- [Where AI coding agents keep historyevery other agent's store](https://ranwhat.com/guides/ai-coding-agent-history-locations)
- [Cursor chat historythe same question for Cursor](https://ranwhat.com/guides/cursor-chat-history)
- [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)
