Continue Codex Work

Overview

Recover actionable context from a prior Codex CLI session and continue execution in the current conversation. Codex records each session as a rollout JSONL under ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl (with an optional state_*.sqlite index). Use those local files as the source of truth, then continue with concrete edits and checks — not just summarizing.

Why this exists instead of codex resume: replaying a full rollout re-feeds every reasoning step, tool call, and tool output back into the context window. For long sessions that wastes the window on resolved turns and stale output. This skill selectively reconstructs only actionable context — the last compaction's surviving requests, recent user/assistant turns, the tool calls and files edited, and how the session ended — giving a fresh start with prior knowledge.

This is the Codex sibling of continue-claude-work. The two are deliberately split because the on-disk formats differ: Claude Code writes ~/.claude/projects/<encoded>/<session>.jsonl, Codex writes ~/.codex/sessions/.../rollout-*.jsonl with a different record schema. Use this skill for Codex sessions; use continue-claude-work for Claude Code sessions.

File Structure Reference

For the rollout directory layout, the record/payload schema, and the compaction format, see references/file_structure.md.

Workflow

Step 1: Extract Context (single script call)

Run the bundled extractor. It handles session discovery (via the shared _core), rollout parsing, noise filtering, and workspace state in one call:

# Latest Codex session for the current project (cwd)
python3 scripts/extract_codex_resume.py

# A specific session by id (full or unambiguous prefix)
python3 scripts/extract_codex_resume.py --session <SESSION_ID>

# Search sessions by a keyword in the title
python3 scripts/extract_codex_resume.py --query "skill migrator"

# List recent sessions for the current project
python3 scripts/extract_codex_resume.py --list

# List across all projects (not just the current cwd)
python3 scripts/extract_codex_resume.py --all-projects --list

# Complete text of long sections (default output truncates and prints this hint itself)
python3 scripts/extract_codex_resume.py --session <SESSION_ID> --full

Expected output: a structured Markdown briefing. What you should see:

• A # Codex Resume Context Briefing header, then ## Session Info (id, project cwd, last-active time, title, Codex version).
• A one-line **Session end reason** — the single most important routing signal (see Step 2).
• ## Compact Summary — if the session was compacted, the surviving user/assistant thread (system preamble and re-injected AGENTS.md are stripped out).
• ## Last User Requests and ## Last Assistant Responses — the most recent turns. Long entries are truncated and end with a rerun with --full hint — that hint means there is more, and names exactly how to get it. A user turn shown as [skill invoked: <name> — injected body omitted] is a skill invocation (Codex delivers the whole bundle as the message; the fact matters, the bytes don't).
• ## Latest Plan State — if the session used Codex's update_plan tool, the single most recent plan call, rendered as a step checklist. This is the highest-signal "what stage is this task at" artifact for a multi-step task, and it survives even in very long sessions where the generic tool-call list below would have evicted or truncated it.
• ## Recent Tool Calls, ## Files Edited in Session (from patch / FileChange records), ## Errors Encountered.
• ## Current Workspace State — git branch, uncommitted changes, recent commits.

If instead you see No Codex sessions found for <path>, the current directory has no Codex history — try --all-projects --list to find the right project, or pass --session <id> directly.

Step 2: Branch by Session End Reason

The briefing's Session end reason tells you how the prior run stopped. Route on it:

Step 3: Reconcile and Continue

Before making changes:

1. Confirm the current directory matches the session's cwd.
2. If the git branch differs from what the briefing shows, note it and decide whether to switch.
3. Inspect the files listed under Files Edited — verify the prior run's changes actually landed (a rollout records that a patch was attempted; confirm the current file state).
4. Do not assume old claims hold without checking — compaction and tool output are lossy.

Then:

• Implement the next concrete step aligned with the latest user request.
• Run deterministic verification (tests, type-checks, build).
• If blocked, state the exact blocker and propose one next action.

Step 4: Report

Respond concisely:

• Context recovered: which session, key findings from the briefing.
• Work executed: files changed, commands run, test results.
• Remaining: pending tasks, if any.

How the Script Works

Session discovery reuses the shared core

Discovery goes through _core.codex.collect_codex (bundled into scripts/_core/), the same schema-tolerant reader the local-conversation-history skill uses: it prefers the state_*.sqlite index and falls back to scanning raw rollout JSONL when the DB is missing or its schema has drifted. So listing, --query, and latest-for-project all share one tested implementation.

Rollout parsing

Codex's rollout schema is not Claude's. The parser reads:

• User / assistant turns from two possible streams, because where turns live drifts by Codex version (measured on ~2,600 rollouts, 0.142.2–0.149.0): the event_msg/user_message / agent_message mirror stream (the norm through 0.146.x and in the 0.147/0.148 alphas, rare residuals after) and response_item/message records (user text is input_text, assistant text is output_text, decoded locally). The streams do not always mirror — some versions keep per-step commentary only in the event stream, and mid-turn queued user inputs appear only in message records — so both are collected and the richer stream wins per role (requests and responses display in separate sections; ties go to the event stream), never double-counting, never silently dropping either role's bigger half. An image-only user message renders as [image-only user message] instead of vanishing. task_complete.last_agent_message is a tail safeguard, appended only when the chosen stream lacks the final assistant text. response_item/agent_message records are inter-agent traffic (sub-agent routing messages, plaintext or encrypted), never main-thread text.
• Files edited from event_msg/patch_apply_end (norm ≤0.146 + alphas; rare residuals later) and from event_msg/item_completed items of type FileChange (0.147+, where patch events vanished) — the keys of the changes map are the files touched; both sources feed one set.
• Tool calls from response_item/function_call and custom_tool_call, paired with their *_output by call_id (an unpaired call means it never returned). The most recent update_plan call gets extra treatment: its full parsed plan (and explanation when present) is tracked separately, last-call-wins, exempt from the 120-char tool-call preview and the last-20 window — measured stable on ~4,000 real calls, always a JSON string parsing to {"plan": [...]} or {"explanation": ..., "plan": [...]}, each step {"step", "status"}.
• Compaction from compacted records — Codex replaces the compacted window with a replacement_history of messages (not a single summary), and re-injects the system preamble; the parser keeps only the user/assistant turns.

Session end reason detection

Classified from the tail of the rollout: a trailing task_complete or final_answer-phase assistant message is completed; unpaired tool calls or a trailing turn_aborted are interrupted; tools that ran with no closing message, or a tail stuck at a commentary-phase message (cut off mid-turn), are in progress; a trailing user message is abandoned; three or more tool failures are an error cascade. A task_complete can also carry an error ({"message", "codex_error_info"}) — measured on a corpus scan of 468 real occurrences across 6,650 rollouts, spanning 6 distinct codex_error_info values. This is captured on every task_complete (last-wins, so a later clean turn correctly clears a stale earlier error) and composed with the closing message rather than treated as mutually exclusive with it: error present and no closing message (466/468 in the scan) is errored, inlining the exact codex_error_info and message; error present but a real closing message anyway (2/468) stays completed, with a caveat noting the error rather than hiding it.

Noise filtering

Codex re-injects large system blocks after compaction and between turns — the permissions block, the agent-role message, and the project's AGENTS.md. The parser drops these using the shared is_noise_text (which recognizes <permissions instructions, <system-reminder, # AGENTS.md instructions for, and similar prefixes) so the briefing shows the real conversation, not the harness scaffolding.

Guardrails

• Do not run codex resume or codex --continue — this skill provides context recovery within the current conversation.
• Do not treat the compact summary or tool output as complete truth — they are lossy. Always verify claims against the current workspace.
• Do not overwrite unrelated working-tree changes.
• Do not load a whole rollout file into context — always use the script (rollouts are routinely multiple MB).

Limitations

• Cannot recover sessions whose rollout files were deleted from ~/.codex/sessions/.
• Cannot access sessions from other machines (files are local only).
• Long briefing sections (compact summary, user requests, assistant responses) are truncated by default; each truncation point prints a rerun with --full hint, and --full prints the complete text (per-section count caps still apply). Tool-call previews stay capped at 120 chars by design — for a full command or patch, grep the rollout for the call's call_id.
• Compaction is lossy — early-conversation detail may be gone.
• Codex has no per-session auto-memory equivalent to Claude Code's MEMORY.md; the project's AGENTS.md is deliberately filtered out as re-injected noise, so read it separately if you need the project's standing instructions.

Example Trigger Phrases

• "continue the Codex session 019f66..."
• "codex got cut off mid-task, pick up where it left off"
• "don't codex resume, just read the rollout and keep going"
• "what was Codex doing in my last session in this repo?"
• "find the Codex run where I built the skill migrator and continue it"

Related Skills

• continue-claude-work — the same capability for Claude Code sessions (~/.claude). If the prior session was Claude, not Codex, use that skill instead.
• local-conversation-history — lists both Claude and Codex conversations across every config home. Use it first when you are not sure which session (or which provider) you want, then bring the Codex session id here.