Sessions, Resume & Forking

Most chat tools treat a conversation as something that lives only in the window — close the tab and it's gone. Codex is different: every interactive session is persisted to disk the moment it starts. Think of a session less like a phone call and more like a document that Codex keeps writing to as you work.

That one fact unlocks everything in this lesson. Because the conversation is a durable artifact, you can:

• Close your terminal and come back tomorrow — the full transcript, including every file edit and command Codex ran, is still there to resume.
• Survive a crash, a reboot, or an accidental Ctrl+C without re-explaining the task from scratch.
• Run genuinely long-horizon work — a migration that spans several days — as one coherent thread instead of a dozen disconnected chats.

The unit Codex persists is a session (also called a thread or a rollout). It carries the model and provider you were using, the working directory, and the ordered list of everything that happened. When you resume, Codex replays that history into context and continues as if you never left.

The rest of this lesson is really just three verbs you apply to that durable file: resume it, fork it, or start a new one — plus knowing where it lives so you can find, copy, or inspect it.

The core command is codex resume. Run it and Codex opens a picker — a list of your recent sessions. Highlight one to see its summary, press Enter, and you're back in that thread with full history.

Most of the time you don't want the picker — you want the session you were just in. There are flags for that:

The directory filter is the subtle part. By default Codex scopes the picker and --last to sessions started in your current working directory, which is usually what you want — you cd into a project and resume that project's work. When you've forgotten which directory a session lived in, combine --last --all to reach across all of them.

Resuming a specific session is the most precise option. You can even hand it a fresh instruction in the same breath:

# Reopen a session by ID and immediately give it a new task
codex resume 0f9c1a2b-... "now add tests for the new endpoint"

Inside an already-open CLI you don't need to quit first — type /resume to load a saved conversation from your session list without leaving the program.

Resuming continues a single line of history. But real work isn't always linear — sometimes you want to try an alternative approach without abandoning the conversation you've built. That's what forking is for.

codex fork [SESSION_ID] starts a new thread that preserves the original transcript as its starting point. The original session stays untouched; your fork is a copy you can take in a different direction. It's the conversational equivalent of git branch: explore a risky idea on a branch, and if it doesn't pan out, the trunk is exactly as you left it.

There are three in-session commands that round out your options without leaving the CLI:

The distinction between fork and new is worth fixing clearly:

• Fork keeps the history and copies it into a separate branch — use it when the accumulated context is valuable and you want to explore a variation.
• New discards the history and starts empty — use it when the context is stale or you're switching to an unrelated task.

This maps directly onto the session-hygiene principle Codex recommends: one thread per coherent unit of work, not one giant thread per project. When you finish a feature and start an unrelated bug fix, that's a /new. When you want to try a second implementation of the same feature, that's a /fork.

Resume and fork feel like magic until you know what they're reading. Codex stores every session as a JSONL rollout file — one file per session, where each line is a JSON record of a single event (the metadata header, then each user message, model reply, command run, and file change in order).

The root directory is $CODEX_HOME/sessions/, which defaults to ~/.codex/sessions/. You can relocate the whole Codex state tree — config, credentials, and sessions — by setting the CODEX_HOME environment variable, which is handy for isolating profiles or running Codex under automation.

~/.codex/
├── config.toml          # your settings
├── auth.json            # credentials
└── sessions/            # one rollout file per session
    └── YYYY/MM/DD/
        └── rollout-<timestamp>-<id>.jsonl

Three properties matter in practice:

• Resuming appends. When you resume a session, Codex adds new events to the existing rollout file rather than creating a new one — so a long-running, repeatedly-resumed task lives in a single growing file.
• The files are plain JSONL. You can read, grep, or archive them with ordinary tools. (Codex also keeps an archived_sessions/ directory for ones you've cleared away.)
• The nested YYYY/MM/DD/ layout is community-reported, not a guaranteed contract. The root ($CODEX_HOME/sessions/) and the JSONL-rollout format are well established; the exact date-nesting and filename pattern come from community/DeepWiki sources and an issue tracker, so don't hard-code a path against them — let codex resume find files for you.

Several commands above take a <SESSION_ID>. A session ID is just the unique identifier Codex assigns each thread (a UUID). There are three reliable ways to get one:

1. From the picker. Run codex resume and the list shows your recent sessions; the picker is the no-memory-required way to find the right thread by its summary.
2. From /status. Inside an active session, /status displays the session configuration and token usage — including the current session's ID. This is the quickest way to grab the ID of the thread you're in right now (for example, to fork it from another terminal).
3. From the session files. Because each rollout is a file under ~/.codex/sessions/, the ID is embedded in the filename and in the file's metadata header. Useful when scripting or when you're reconstructing what happened after the fact.

In practice you'll lean on the picker for interactive work and on /status (or the headless event stream) when you need to capture an ID programmatically.

Everything so far has been interactive, but the same persistence model works for codex exec — the non-interactive command used in CI, cron jobs, and scripts. Headless runs are sessions too: they persist under ~/.codex/sessions just like interactive ones (unless you opt out).

codex exec resume mirrors the interactive flags exactly:

This is what makes multi-step automation possible: a first job kicks off a task and records its session ID, and a later job resumes that exact thread to continue — for example, a pipeline that plans on one trigger and implements on the next.

# Step 1: start a task headlessly and capture the thread it created
codex exec --json "draft a migration plan for the users table" > step1.jsonl

# (parse the thread/session id out of the JSONL event stream)

# Step 2 (later run): resume that exact session and continue the work
codex exec resume <SESSION_ID> "now generate the migration files"

If you don't want a run to persist — a throwaway check that shouldn't clutter your session history — codex exec supports an --ephemeral flag that skips writing the rollout to disk.