Sessions, resuming and forking

Back to the Codex learning hub

Goal and preparation

Resume continues prior conversation/session state; it does not rewind the disk. Recheck files edited by you or another task. Distinguish it from forking and host handoff: continuing an existing task, creating another line of work and moving execution are different operations.

Step 1: Create two distinguishable labs

Create codex-session-a and codex-session-b under one practice parent, each with note.txt. Put the first sample in A and the second in B, not both in one file. Matching filenames but distinct markers prevent filename-only assumptions. Record the parent location and verify your directory before each launch.

SESSION-A
Revision: 1

SESSION-B
Revision: 100

Open A in the editor and integrated terminal. Use Get-Location in PowerShell or pwd on macOS/Linux to confirm codex-session-a, then run the command and send the following prompt inside CLI. Expect A's actual directory, SESSION-A and Revision: 1 without edits. Record the visible session title and time.

codex --cd . --sandbox read-only

Read note.txt from the current directory without changing files. Report the exact directory and both lines. This is a session-resume exercise. Do not search other folders or infer content from the filename.

Exit A with /exit, wait for the shell prompt, then open the same read-only workflow from B. Expect SESSION-B and Revision: 100. Exit again. You now have two identifiable sessions: B is newer, but the next goal is A. This makes selection verifiable instead of relying on a single recent task.

Step 2: Select A from the session list

From A's shell run codex resume. Inspect the displayed path, time and available preview before choosing A. Use --all if you need sessions outside the current directory, then verify the selection rather than equating globally newest with intended. Follow the picker's visible controls and read the path before confirming with Enter.

codex resume

codex resume --all

When current and saved directories differ, CLI may ask which to use. Choose A's location deliberately, then verify with /status and a fresh read. Existing tui.resume_cwd or explicit --cd can change that behavior; see configuration troubleshooting. Absence of a directory prompt does not prove the selected path is correct.

Step 3: Verify current disk contents after resuming

Exit A and change only A/note.txt's second line to Revision: 2 in your editor. Keep B untouched. From A run the command below: --last is documented as scoped to the current directory, unless --all expands the search. If A contains other sessions too, use the picker or known ID instead of assuming its newest session is the lab.

codex resume --last --sandbox read-only

Send the request below. Expect the old conversation to say Revision: 1 while disk says Revision: 2, with SESSION-A unchanged. That discrepancy is the exercise, not a defect to repair by restoring remembered text. The same method checks whether test records, uncommitted changes and handoff notes still describe current work.

Resume by reading note.txt from disk again now. Compare the current revision with the earlier conversation. Report the current directory, the file marker, and any difference. Do not restore an older value or edit any file.

Extension: verify files after forking a chat

To explore another approach, exit the CLI, return to A and run fork below. Select the original A session by its details and directory, then record the new session ID. This branches the conversation, not a file backup. This non-Git exercise uses no worktree; both chats may access the same folder, so keep both read-only. If unavailable, check codex fork --help and your version.

codex fork --sandbox read-only

This is a read-only alternative branch of the session exercise. Read note.txt from disk now and report its actual path, marker and revision. Describe one different way to verify the file without changing it. Do not assume that forking created a separate file copy or restored Revision: 1. Do not edit files.

The fork should still read A's current Revision: 2 while the original conversation remains. If both sessions use the same absolute path, record separate chats with shared files. Exit the fork, select the original A session and read again. Closing or deleting a chat is not file restoration; Worktrees covers Git working-directory isolation.

Troubleshooting, stopping and restoration

For a missing session, check OS, user, CODEX_HOME and host, then inspect other directories with --all. Matching desktop/CLI titles do not prove interchangeable session stores. If you choose B, stop further requests and /exit before selecting A. If writes occurred, inspect the actual changed directory; leaving the conversation does not undo them. For a stale revision, request a fresh read and verify the path instead of repeating “continue.”

If instruction files changed, finish the current small step and verify a fresh session; resume is not a universal reset of prior instructions. See instruction scopes. For long conversations, use context handoff to retain decisions, actual files and pending work, without treating a summary as a backup.

Retain A/B identification, the fresh resumed read and an explanation of --last versus --all. Reset only A to revision 1 and verify B remains 100; no session or authentication deletion is needed. Commands are documentation/help-checked, not claims of a reader's interactive execution or automatic cross-platform synchronization. Before real edits, identify task, directory and current version.

Diagram 1 distinguishes A and B, 2 selects the correct session, and 3 rereads disk and verifies the revision. Retain these three checkpoints whenever resuming.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex