How to Resume a Codex Session and Find Its History
Related guide: Codex usage limits and when they reset
Codex saves each session as a JSONL file under ~/.codex/sessions/, in a folder for the day it started, on the machine that ran it. Run codex resume to pick one from a list, codex resume --last to reopen the newest one from the current directory, or type /resume inside a session. Codex doesn’t expire them, so a session stays on disk until you delete it.
Want your team's Codex history in one place? Zest uploads each engineer's Codex sessions, with model, tokens and tool calls, and links each one to the pull request it led to. Start freeGet started
The list doesn’t show everything in that folder. On one of our engineers’ laptops, 188 of the 368 Codex sessions between June 21 and September 22, 2026 were subagent threads, and the resume picker leaves those out, along with codex exec runs. The commands below are from OpenAI’s Codex docs, checked against the source of Codex 0.167.2, released November 11, 2026.
Where does Codex store session history?
Each session is one file:
~/.codex/sessions/YYYY/MM/DD/rollout-<date>T<time>-<session-id>.jsonl
The UUID after the timestamp is the session ID that codex resume takes. Setting CODEX_HOME points Codex at another directory instead of ~/.codex, and that directory has to exist already. On Windows the default is %USERPROFILE%\.codex.
The first line is a session_meta record: the session ID, working directory, git branch and commit, model provider, Codex version, and which app wrote the file. Every line after it is one JSON object, such as a message, a tool call, a command’s output or a token count.
| What | Path under ~/.codex/ |
How long it stays |
|---|---|---|
| Session transcripts | sessions/YYYY/MM/DD/ |
Until you archive or delete it |
| Archived sessions | archived_sessions/ |
Until you unarchive or delete it |
| Prompts you typed | history.jsonl |
Until you delete it, unless you cap it |
Names from /rename |
session_index.jsonl |
Until you delete it |
Subagent threads get files of their own. In those, source is an object naming the parent thread, where a top-level session has a plain string such as cli, vscode or exec. If you count sessions with a script, filter on that field first. Keeping only files whose source is a string leaves the subagents out.
The ChatGPT desktop app and the IDE extension keep local chats in the same folder, so codex resume in a terminal can list a chat you started in the app. When the app and the extension are open on the same project, they share active chats.
Cloud tasks don’t live here. They run in OpenAI’s cloud and stay in your ChatGPT account. codex cloud, still marked experimental, browses them from the terminal, and codex cloud list --json prints the recent ones for a script.
How to resume a Codex session
| You want | Run |
|---|---|
| The newest session from this directory | codex resume --last |
| The newest session from any directory | codex resume --last --all |
| A list to pick from | codex resume, or /resume inside a session |
| One session, by ID or by name | codex resume <session-id> or codex resume auth-refactor |
codex exec runs in the list as well |
codex resume --include-non-interactive |
| A copy that leaves the original alone | codex fork, or /fork inside a session |
codex resume and codex fork both take a prompt after them, which Codex sends as soon as the session opens. There’s no codex continue command or --continue flag. codex resume --last is the counterpart of claude -c, and our post on Claude Code session history covers the Claude side.
The picker lists sessions from the current directory, most recently updated first. Press Tab to move between its three controls and the left and right arrow keys to change one:
- Filter:
Cwd, thenRepo, which adds the project’s linked git worktrees when it has any, thenAll. - Status:
ActiveorArchived. - Sort:
UpdatedorCreated.
Typing narrows the list by each session’s first message, name, ID, git branch and directory. It doesn’t search the rest of the conversation. Ctrl+T shows the selected session’s transcript, and Ctrl+A archives it.
When you quit, Codex prints the codex resume <session-id> command for the session you were in. To make one easier to find later, name it with /rename, or start it with a name: /new bug bash or /clear release prep. By ID, codex resume finds a session from any directory.
If you resume from a different directory than the one the session ran in, Codex asks which to use. Set tui.resume_cwd to "current" or "session" in ~/.codex/config.toml to skip the question, and -C <dir> overrides both.
[tui]
resume_cwd = "session"
How to fork a Codex session
A fork copies a session into a new one with its own ID and leaves the original transcript as it was. Inside a chat, /fork forks the current one and may ask whether to stay in this directory or use a new worktree. Press Esc twice with an empty composer to edit your last message and fork the chat from that point instead.
From the terminal, codex fork opens the same picker, and --last takes the newest session from this directory (add --all for any directory). To fork into a new managed Git worktree, pass the session’s ID:
codex fork <session-id> --worktree
For scripts, codex exec fork <session-id> "try another approach" copies a saved session and runs the prompt in the copy. Leave the prompt off and Codex creates the fork without starting a turn.
How to resume a codex exec run
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
--last takes the newest session from the current directory, and --all looks in every directory. It doesn’t stop at exec runs: in the 0.167.2 source it considers every kind of session, interactive chats and subagent threads included, so the one it picks may not be your last exec run. In a pipeline, pass the ID. With --json, Codex prints a thread.started event whose thread_id is that ID:
codex exec --json "review the change for race conditions" > run.jsonl
codex exec resume "$(jq -r 'select(.type == "thread.started") | .thread_id' run.jsonl)" "fix the race conditions you found"
A run with --ephemeral writes no session file, so there’s nothing to resume. Exec runs stay out of the interactive picker unless you add --include-non-interactive.
Why a Codex session is missing
- It ran in another directory.
codex resumeand--laststart from the current one, so set the picker’s filter toAllor add--all. - It’s archived.
/archive,codex archiveandCtrl+Ain the picker move a session to~/.codex/archived_sessions, with any subagent sessions it spawned. Switch the picker’s Status toArchived, or runcodex unarchive <session>. - It wasn’t an interactive chat.
codex execruns appear only with--include-non-interactive, and subagent threads never do. In a running chat,/subagentsswitches to one of its agent threads. - You changed model provider. Since Codex 0.167.0 those chats stay in the list, but one recorded with another provider opens read-only: “This chat uses X, but Codex now uses Y, so this chat is read-only.” Switch back to continue it, or read its transcript and start a new chat from it.
- It lives somewhere else. Cloud tasks stay in ChatGPT. Codex inside WSL uses the Linux home, so it doesn’t see the Windows app’s sessions until you set
CODEX_HOME=/mnt/c/Users/<windows-user>/.codex. AnotherCODEX_HOME, or another machine, has a folder of its own. - It was never saved, or it’s gone.
--ephemeralruns write no file, andcodex deleteor/deletepermanently removes a transcript along with the sessions it spawned. - You’re looking in the desktop app. Its sidebar can filter chats out: choose Chronological from the filter icon next to Chats, and check Archived chats in Settings.
If the list still looks wrong, codex doctor reports on the thread inventory as well as the install, config and auth.
How long does Codex keep session history?
Until you remove it. The config reference has no retention setting for sessions, and we found no code in the 0.167.2 source that deletes old ones, so ~/.codex/sessions keeps growing. To prune it:
codex archive <session-id> # hide it from the picker, keep the file
codex delete <session-id> --force # delete it without asking (UUID only)
Without --force, codex delete asks first. The flag only takes a UUID, so a name that several sessions share always gets the prompt.
history.jsonl is a separate file, with a line for each prompt you typed, its session ID and a timestamp. It’s what the Up arrow and Ctrl+R search through in the composer. To stop saving it:
[history]
persistence = "none"
To keep it but cap its size, set max_bytes in the same table, and past the cap Codex drops the oldest lines. OpenAI’s config pages describe these two as settings for saving transcripts, but in the 0.167.2 source they don’t touch session files: persistence covers history.jsonl and the composer’s recent-mentions file, mention_usage.json, and max_bytes caps history.jsonl only. With persistence off, session files are still written and codex resume still works. In a script, codex exec --ephemeral is how you leave no session file.
Session files hold what Codex saw: your prompts, its replies and the output of the commands it ran. An API key that a command printed stays in that file for as long as the file does. /feedback sends logs to OpenAI, and the current session too if you choose to share it.
How to search or export Codex history
The picker’s search stops at names and first messages. To search inside sessions, run ripgrep over the files, which are plain text:
rg -l "rate limiter" ~/.codex/sessions ~/.codex/archived_sessions
To list sessions with the directory each one ran in, read the first line of every file:
for f in ~/.codex/sessions/*/*/*/*.jsonl; do
head -1 "$f" | jq -r '[.payload.id, .payload.cwd] | @tsv'
done
Codex has no export command. /copy copies a response, a code block or a quote, and the JSONL file is the full record. Two third-party tools read these files. Claude Code History Viewer is a desktop app that, despite its name, reads Codex CLI sessions too and describes itself as 100% offline. agent-history is a CLI that exports Codex sessions to Markdown or HTML. We haven’t tested either.
Don’t build on the file format. OpenAI doesn’t document it, and it’s moving: 0.167.2 ships codex migrate-rollouts, which converts older sessions to a newer paginated format, and has an off-by-default local_thread_store_compression feature that rewrites sessions older than a week as .jsonl.zst, which the rg and head -1 commands above don’t read. Scripts hold up better on codex exec --json, or on the app server’s thread/list and thread/turns/list methods, which OpenAI does document.
How to see a teammate’s Codex sessions
Not from Codex: a teammate’s local sessions stay on their laptop.
We make Zest for the team view. Its Codex plugin (setup) works from the same files. While you work, it reads that day’s sessions in ~/.codex/sessions once a minute, redacts secrets on the machine and uploads each session’s prompts, replies, model, token counts, skills and tool calls to the team’s workspace, then stops 10 minutes after your last prompt. A GitHub App links each session to the pull request it led to.
It won’t import old history, because it only reads sessions active that day, and it doesn’t record subagent threads. It doesn’t put a session back in anyone’s terminal either, so codex resume still needs the file on your own disk. Every engineer has to install the plugin, pull request links need GitHub, and no code diffs are collected. Reading another engineer’s raw prompts and replies takes an owner or admin role in the workspace.
Questions about Codex session history
How do I resume my last Codex session?
Run codex resume --last from the directory you worked in, or add --all to reopen the newest session from any directory.
Do /new and /clear delete the current session?
No. Both start a new chat and leave the old one saved, so /resume brings it back. /clear also clears the terminal, while Ctrl+L clears the terminal and keeps the current chat.
Can I recover a deleted Codex session?
codex delete and /delete are permanent, and OpenAI documents no undo, so the way back is a backup of ~/.codex/sessions. An archived session isn’t deleted: codex unarchive <session> restores it, with the subagent sessions it spawned.
Where is Codex history on Windows?
It’s in %USERPROFILE%\.codex\sessions\, which the Windows app and native Codex share. Codex inside WSL uses ~/.codex in the Linux home instead, unless you point CODEX_HOME at the Windows folder.
Can I resume a Codex session on another computer?
Not from local history, since the file is on the machine that ran it. Cloud tasks are the exception, because they live in your ChatGPT account. On one machine, /app moves a CLI session into the ChatGPT desktop app on macOS and Windows. OpenAI doesn’t document copying a session file from one computer to another.
Can I bring my Claude Code history into Codex?
Partly. /import in the Codex CLI brings over setup, project files and up to 50 chats from the last 30 days from Claude Code or Cursor, and it leaves the other agent’s setup as it was.
Commands, paths and settings are from OpenAI’s Codex docs on CLI commands, non-interactive mode, advanced config, the config reference, environment variables, troubleshooting, the Windows app, IDE settings, importing and the app server, read on November 11, 2026. The picker’s controls, the history settings and the file layout were checked in the openai/codex source at release 0.167.2, and the provider change in its 0.167.0 release notes.
See what a team's AI coding agents shipped this week
A live Zest workspace with sample data: which agents, models and skills each engineer used, what they cost, and the pull requests they merged.
Open the live team demoSample data, no signup
Zest is AI coding analytics for engineering teams: it shows which coding agents, models and skills each engineer uses, what they cost, and which sessions end in merged pull requests. See how Zest works.