Field guide / 10 min
Resume, fork, archive, and restore Codex sessions
Treat saved context as state with lineage, not as a magic continuation button.
Codex persists interactive and exec sessions so work can continue later. resume continues a lineage; fork creates a branch; archive and unarchive provide reversible housekeeping; delete permanently removes the selected saved session. The safe unit of continuation is the pair of an exact session and a compatible repository state.
Verified terminal sequence
- $
codex resume --last - $
codex fork --last - $
codex archive SESSION_ID - $
codex unarchive SESSION_ID - $
codex delete SESSION_ID
Working principles
History does not freeze Git
A transcript can survive while the branch, files, dependencies, and instructions change. Reconcile the checkout before continuing.
Fork preserves the original
Use a fork when exploring another solution or when the original lineage must remain a stable audit trail.
Archive before delete
Archive is reversible; delete is permanent. Routine cleanup should not use permanent deletion.
Field procedure
- 01
Identify the target
Use the picker or an exact session ID. --last is convenient for a human at one checkout, but is ambiguous in unattended automation.
- 02
Reconcile repository state
Compare branch, HEAD, working tree, instructions, and dependencies with the state the session expects.
- 03
Choose continue or branch
Resume when the goal and lineage are unchanged; fork when testing a separate direction.
- 04
Use reversible housekeeping
Archive inactive sessions and verify they can be found and restored before considering deletion.
- 05
Delete only an exact target
Confirm the identifier, retention need, and absence of unique evidence before the permanent command.
PASS / FAIL
Acceptance checklist
- The session ID and repository match.
- Resume versus fork is intentional.
- Archive is the default cleanup action.
- Permanent deletion is never selected by a fuzzy query.
- Sensitive transcripts follow the project retention policy.
WATCH / REJECT
Failure patterns
- Resuming “last” from the wrong repository.
- Treating forked work as if it modified the original lineage.
- Deleting when the actual goal was to hide inactive sessions.