Codex Session Browser

Use the bundled parser instead of hand-grepping raw JSONL.

Preferred entrypoint:

• python3 scripts/codex_sessions.py list --repo /abs/repo/path
• python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 3 --tail 10

What this skill knows

• Codex sessions live under ~/.codex/sessions/YYYY/MM/DD/*.jsonl.
• The repo or worktree is recorded in session_meta.payload.cwd near the top of each file.
• Plain conversation text is easiest to extract from event_msg records:
• user_message -> user prompt text
• agent_message -> assistant text output, with phase such as commentary or final_answer
• Tool calls and tool outputs live in other record types such as response_item with function_call, function_call_output, or custom_tool_call; ignore them unless the user explicitly asks for tool traces.
• Some sessions may not have event_msg conversation entries. In that case the parser falls back to response_item records whose payload is a plain message from user or assistant.

Workflow

1. Identify the target repo or session.

• For one repo/worktree, use --repo /absolute/path for exact cwd matching.
• If the exact path is unknown, use --cwd-contains partial-name first.
• If the user already knows a session id or filename fragment, use messages --session <id-or-path>.

1. List candidate sessions first.

• Run python3 scripts/codex_sessions.py list --repo /abs/repo/path --limit 10
• This shows session timestamp, file path, repo cwd, message count, and short previews of the last user and assistant text.

1. Extract plain conversation text.

• Run python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 1 --tail 8
• This prints only user/assistant text messages, not tool calls.
• Increase --limit-sessions to inspect multiple recent sessions.
• Use --tail 0 to print the full text conversation for each matched session.

1. Narrow the assistant output when needed.

• Use --assistant-phase final_answer when the user wants only final answers.
• Use --assistant-phase commentary when the user wants progress updates instead.
• Use --role user or --role assistant to isolate one side.

1. Use JSON output when another script or agent will consume the result.

• python3 scripts/codex_sessions.py list --repo /abs/repo/path --json
• python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 3 --tail 12 --json

Examples

Find the latest forgedemy Codex sessions:

python3 scripts/codex_sessions.py list \
  --repo /home/latand/Projects/forgedemy \
  --limit 5

Pull the last few prompts and replies for that repo, without tool calls:

python3 scripts/codex_sessions.py messages \
  --repo /home/latand/Projects/forgedemy \
  --limit-sessions 2 \
  --tail 8

Only show final assistant answers from the latest matched session:

python3 scripts/codex_sessions.py messages \
  --repo /home/latand/Projects/forgedemy \
  --assistant-phase final_answer \
  --tail 4

Inspect one exact session by filename fragment:

python3 scripts/codex_sessions.py messages \
  --session 019cf134-ec89-77d3-a78f-1710bc2a8c03 \
  --tail 0

Reporting back

When summarizing results for the user, include:

• the matched repo path or session id
• the session timestamp
• the last relevant user prompt(s)
• the assistant reply text the user actually cares about
• a note that tool calls were excluded unless the user asked for them