BuildGist

Codex session history: where it lives and how to reopen a chat

Kayvan Zahiri ·

Codex keeps its local state, sessions included, under CODEX_HOME, which is ~/.codex unless you set it to another folder. To get a chat back, run codex resume and choose it from the session picker, or run codex resume --last to skip the picker and reopen the most recent chat from the folder you are in.

What is in ~/.codex

Codex's environment variables page, read on October 19, 2026, calls CODEX_HOME the root for Codex state: config, auth, logs, sessions and skills. The CLI, the IDE extension and the app server all use it. If you point it at another folder, that folder has to exist first.

Codex's advanced configuration page names the files you may see there:

Some resumable state is kept in a SQLite database. It sits in CODEX_HOME too, unless CODEX_SQLITE_HOME or the sqlite_home key moves it.

What the docs leave out

Blog posts and scripts describe a folder layout for single sessions inside ~/.codex. Codex's documentation does not describe that layout or the format of the files in it, so this page does not either, and a script built on it can break with any release. For a copy you can read, open the chat in Codex and type /export session.md. Codex writes the whole conversation to that file as Markdown. Wait for the current turn to finish first.

Reopen a chat

Codex's developer commands page, read the same night, gives these ways back in:

Runs you started with codex exec are left out of the picker and out of --last unless you add --include-non-interactive. They also have their own codex exec resume.

A resumed chat reloads its transcript and the original history stays intact. If you are now in a different folder from the one the session ran in, Codex asks which folder to use. Set tui.resume_cwd to "current" or "session" in config.toml to stop the question. An explicit --cd still wins over it.

Give the chats you will want a name

Type /rename and a short name, say /rename billing-retry. Only the saved name changes; the transcript does not. That name works with codex resume, codex archive and codex delete, so next week you type a word instead of hunting for an ID.

Find a prompt you typed

Press Ctrl+R in the composer to search your prompt history. Enter uses the match and Esc cancels. The up and down arrows bring back earlier drafts. This searches what you typed, not what Codex answered. For an answer, resume the chat or export it.

Branch, hide or delete a session

How long Codex keeps it

The docs give no number of days. They give two keys in the [history] table of config.toml. persistence takes save-all or none, and this turns saving off:

[history]
persistence = "none"

max_bytes caps the size of the history file. Once the file passes the cap, Codex drops the oldest entries and keeps the newest. The docs' own example is 100 MiB:

[history]
max_bytes = 104857600

Before you lower the cap or turn saving off, export the chats you still need.

Which of these is your situation

What the transcript is not

A Codex transcript records the conversation. The code is somewhere else: the files Codex changed are in your project folder, and git status and git diff show them whether or not anything was committed. Reading a run in a useful order is in how to review what Codex changed, and putting files back is in how to undo Codex changes.

The transcript also stays inside Codex. Claude Code and Cursor cannot resume it. To move the task, carry the task itself: a short note with what you asked for, what is done and the next step, or Continue on the BuildGist card when you start a new chat in the same project. What moves and what stays is in can you resume a coding agent session in a different tool?

BuildGist explains each meaningful Claude Code, Cursor and Codex run in plain English and puts the explanation in your Inbox. It comes from the run's changes, not from the chat. It is written by AI, so check important behavior against the code and tests.

Sources

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 Download for Mac

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

Related

Questions: kayvanandre@gmail.com.