Codex Plus Session

Codex Session Lookup

Retrieve context from Codex CLI session history stored at ~/.codex/sessions/.

Session Structure

~/.codex/sessions/YYYY/MM/DD/rollout-{timestamp}-{UUID}.jsonl

Each JSONL file contains:

• session_meta: id, cwd, model_provider, cli_version, base_instructions, git info
• event_msg (agent_message): final agent output
• response_item (type=reasoning): reasoning blocks — plaintext in summary[].text; encrypted_content is opaque
• response_item: user prompts, tool calls (function/custom/search/image)
• turn_context: per-turn metadata (model, effort, sandbox)

Workflow

1. Identify Session

Determine what the user wants to find:

• Partial or full UUID — direct lookup.
• "recent" / "latest" — show recent sessions.
• Topic or keyword — search via grep across sessions.

2. Execute Extraction

Use the helper script:

# Find by UUID (partial match supported)
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/codex-session-extract.py <partial-uuid>

# Include reasoning blocks
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/codex-session-extract.py <partial-uuid> --full

# List matches only (no content extraction)
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/codex-session-extract.py <partial-uuid> --list

# Show recent sessions
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/codex-session-extract.py --recent [N]

For keyword-based search (no UUID provided):

grep -rl "keyword" ~/.codex/sessions/ --include="*.jsonl" | head -10

3. Present Results

Summarize the extracted context:

• Session metadata (model_provider, cwd, git branch, instructions)
• User prompts that initiated the session
• Agent output (final messages)
• Tool calls summary
• Token usage stats

4. Follow-up Options

After presenting context, offer via AskUserQuestion:

• Resume session: hand off to /codex skill with --resume
• View reasoning: re-run with --full flag
• Extract specific content: grep for particular sections
• Copy to current context: incorporate findings into current task

Error Handling

• No matches: suggest --recent to browse available sessions
• Multiple matches: display list table, use first match or ask user to pick
• Large output (>500 lines): truncate agent messages and offer --full separately