Quick answer
Codex writes one JSONL file per session under `~/.codex/sessions`, and keeps them until something deletes them. There is no fixed retention period and no cloud copy by default. How far back you can look depends entirely on whether those files still exist on the machine.
What a session file contains
- Timestamp and session identifier.
- Working directory and model.
- User and assistant messages.
- Tool calls and their output.
- Token count events with input, cached, output, and reasoning.
The file is append-only during a session. A crash can leave the last line incomplete, which is why a parser should skip malformed trailing lines instead of failing.
Retention in practice
| Event | Effect on history |
|---|---|
| Normal use | Files accumulate |
| Reinstall of Codex | Usually kept, unless the home folder is wiped |
| Cleanup script | Deleted permanently |
| New machine | No history until files are copied |
| Container rebuild | History lost with the container |
Keep the history you need
- Back up
~/.codex/sessionswith your dotfiles. - If you use containers, bind-mount the folder.
- Export monthly totals before archiving old files.
- Store exports outside the sessions folder so cleanup does not remove them.
UsageAtlas keeps 7, 30, or 90-day views over the same files, but it is a reader, not a backup.
Build a history you can compare
Session files give you raw history; a comparison needs a fixed window. Pick 7, 30, or 90 days and keep the same window every time you review, otherwise a busy week looks like a trend.
| Question | Window | Why |
|---|---|---|
| Did today go wrong? | Today | Catch a runaway session |
| Is this week normal? | 7 days | Compare with last week |
| Did a plan change help? | 30 days | Smooths out spikes |
| Is the trend real? | 90 days | Shows seasonality |
UsageAtlas keeps those three ranges from local sessions, and the token usage guide explains the fields each total contains.
Questions, answered
How long does Codex keep usage history?
Indefinitely on disk, unless the files are deleted. There is no automatic expiry, and no cloud backup by default.
Can I see Codex history in the CLI?
The CLI resumes a session but does not provide a historical usage report. Read the session files or use a tracker.
Does Codex sync history across devices?
No. Sessions are local. Copy the folder or use an export if you need them on another machine.