Resume work started in OpenAI Codex CLI by reading its conversation history.
Data Locations
There are two history.jsonl files and, depending on Codex version, session files or SQLite state:
| Source | Path | Content |
|---|---|---|
| Global prompt index | ~/.codex/history.jsonl |
User prompts with session_id links |
| Per-project prompt index | <project-root>/.codex/history.jsonl |
Same format, scoped to one repo |
| Session logs (legacy) | ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl |
Full conversations |
| SQLite state | ~/.codex/state_5.sqlite |
Newer storage, may contain thread data |
Session files may not exist in newer versions, so prefer history.jsonl first and treat session JSONL as an optional richer source.
Workflow
Step 0: Search By Keyword
When the user describes the chat by topic rather than session ID, search prompt text across the global and per-project history files.
Step 1: Search By Session ID
Check both global and per-project history files because the session may have started in another repo.
Step 2: List Recent Sessions
If the user does not know which session they want, show recent prompts with timestamps and session IDs.
Step 3: Try To Find A Session JSONL File
If a matching session log exists, use it for richer extraction. Do not fail the workflow if it does not exist.
Step 4: Extract Conversation
- If a session JSONL exists, extract user and assistant messages plus relevant tool calls.
- If it does not, reconstruct the task flow from
history.jsonlentries for the samesession_id.
Step 5: Pick Up The Work
After reading the history:
- Summarize what Codex was working on.
- Note incomplete steps or terminal errors.
- Confirm what the user wants to continue.
- Resume from the last useful state.
Tips
- Session logs can be large, so extract rather than reading raw JSONL manually.
cwdmetadata is useful for locating the repo Codex worked in.- If the user says "continue from codex" without specifics, start by showing recent sessions.