Codex Session Resume skill for Codex

A resume is done well when the right session is reopened in the right directory, the agent re-checks what changed on disk since the transcript ended, and work continues from a stated next step instead of redoing or contradicting earlier turns.

Pick the mechanism

Goal	Command
Continue the newest interactive session in this directory	codex resume --last
Choose from a list	codex resume (picker), or /resume inside the TUI
Search sessions from every directory	codex resume --all
Include codex exec runs in the picker / --last	codex resume --include-non-interactive
Continue a specific session	codex resume <SESSION_ID or name> "next instruction"
Second stage of a scripted pipeline	codex exec resume --last "fix what you found" or codex exec resume <ID> "..."
Explore an alternative without touching the original	/fork, codex fork --last, or codex fork <ID>
Fork into a fresh worktree	codex fork <ID> --worktree (explicit id required)
Resume from code	codex.resumeThread(threadId) in @openai/codex-sdk

--last is scoped to the current working directory unless you add --all. Session names come from /rename; UUIDs win when an argument parses as one. Flags are version dependent: confirm with codex resume --help and codex exec resume --help.

Workflow

- [ ] 1. Identify the session
- [ ] 2. Reopen it in the correct directory
- [ ] 3. Reconcile transcript with the current repo
- [ ] 4. Restate the plan and the next step
- [ ] 5. Continue, checkpointing as you go

1. Identify the session

Transcripts are JSONL rollout files:

ls -t ~/.codex/sessions/*/*/*/rollout-*.jsonl | head -5        # newest first
ls ~/.codex/archived_sessions | tail -5                       # archived ones
grep -l "rate limiter" ~/.codex/sessions/2026/10/*/rollout-*.jsonl   # search by content

The filename ends with the session UUID (rollout-2026-10-02T15-42-47-<uuid>.jsonl). Respect CODEX_HOME if it is set. For codex exec, capture the id up front instead of searching later:

codex exec --json "review src/auth for race conditions" > run.jsonl
SESSION_ID=$(head -1 run.jsonl | jq -r 'select(.type=="thread.started") | .thread_id')
codex exec resume "$SESSION_ID" "fix the races you found, smallest change first"

Runs started with --ephemeral are never written to disk and cannot be resumed. Archived sessions must be restored first: codex unarchive <SESSION>.

2. Reopen in the correct directory

When the current directory differs from the session’s saved directory, Codex asks which one to use. Answer deliberately: resuming a session in the wrong checkout makes every file reference in the transcript point at the wrong code.

• Pass -C <dir> to force a directory for this run.
• Set tui.resume_cwd = "session" (always use the saved directory) or "current" in ~/.codex/config.toml to stop the prompt.
• You may change model or sandbox at resume time (-m, -s, -a); state why if you do, because the earlier turns were planned under the old settings.

3. Reconcile transcript with the repo

The transcript is a record of the past. Before acting on it, compare it with now:

git status --short
git log --oneline -10
git diff --stat
git stash list

Then answer in the chat, briefly:

• Which edits from the transcript are present on disk, and which are missing?
• Did anyone (human, CI, another agent) commit since the session ended?
• Were any commands still running when the session stopped (dev servers, migrations)? Re-run checks rather than trusting their last reported output.

If the repo moved on substantially, fork rather than resume, or start a new chat seeded with a handoff note (see agent-handoff-notes).

4. Restate the plan

Send one message that pins the continuation:

Resuming. Before doing anything, list: (1) what was finished, (2) what is
half-done on disk, (3) the next concrete step. Then run the test command from
AGENTS.md and report the result before editing.

For long sessions, run /compact after the restatement if /status shows the context window is mostly used; the compacted summary then starts from an accurate state.

5. Continue with checkpoints

Commit or note progress at each verified step so a second interruption costs minutes, not the whole session. Use /rename to give the session a findable name.

Housekeeping

Action	Command	Reversible
Name a session	/rename <name>	yes
Hide from lists, keep transcript	/archive or codex archive <SESSION>	yes, codex unarchive
Export a readable transcript	/export session.md	n/a
Summarize without compacting	/recap	n/a
Delete transcript permanently	/delete or codex delete <SESSION>	no

Never delete a session without explicit user confirmation; archive instead.

Gotchas

• codex resume --last picks the newest session for this directory only; from a subdirectory or another worktree it may find nothing or the wrong one. Use --all and check the CWD column.
• Non-interactive runs are hidden from the picker unless you pass --include-non-interactive.
• If the original session ended because safety monitoring paused it, the CLI cannot resume it; start a fresh chat after reviewing what happened.
• Resuming does not re-run setup: environment variables, background terminals and started servers from the old run are gone.
• Two terminals resuming the same session produce interleaved history. Fork for parallel lines of work.
• Session files contain prompts, command output and possibly secrets that appeared in output. Review before sharing; never commit ~/.codex/sessions.
• history.persistence = "none" stops Codex writing history.jsonl; check the setting if expected history is missing.

Verification

• /status after resuming shows the expected model, approval policy and writable roots, and the directory matches the saved session.
• The first post-resume message lists finished, half-done and next items that match git status and git log.
• The project’s test command runs and its result is reported before new edits.

Output template

**Resumed:** <session name or id> in <directory>
**Gap since last turn:** <commits/changes found, or "none">
**State:** done: ... | half-done on disk: ... | not started: ...
**Next step:** <one concrete action> — verification: <command>