Codex Thread Reader

Use this skill when

• The user gives a codex://threads/<uuid> link, a bare thread uuid, or asks about "那个 codex 线程 / 主控线程 / session".
• You need the context of a previous Codex run (what was asked, what was decided, what got merged) before continuing work.
• You need to grep a huge rollout (hundreds of MB) without loading it into context.

Do not cat, head, or rg the rollout file directly: main threads are 100–500 MB JSONL with encrypted reasoning blobs and full tool outputs. Always go through the script.

Where threads live

• Codex Desktop / CLI can run with several CODEX_HOMEs on this machine: ~/.codex, ~/.codex-work, ~/.codex-personal, ... A codex://threads/<id> link does not say which home owns it; the script searches all of them.
• Each home stores a thread as sessions/YYYY/MM/DD/rollout-<local-ts>-<thread-id>.jsonl (archived: archived_sessions/), and indexes it in state_*.sqlite table threads (id, rollout_path, title, cwd, model, archived, ...).
• Thread ids are UUIDv7: the first 12 hex chars are a unix-ms timestamp, so the date directory can be derived even when the sqlite index is stale.
• Rollout record types: session_meta, turn_context, event_msg (task_started, item_completed, task_complete, turn_aborted, token_count), response_item (message with role + phase = commentary|final_answer, custom_tool_call, function_call, reasoning), compacted, world_state, token_usage_record. Real user prompts are item_completed → UserMessage; the app wraps them in ambient blocks (<in-app-browser-context>, <environment_context>, ## My request:) that the script strips. The final answer of a turn is task_complete.last_agent_message (also message with phase=final_answer).

Quick start

S="{baseDir}/scripts/codex_thread.py"
THREAD_REF="codex://threads/<thread-id>"  # replace with the target thread link
python3 "$S" locate  "$THREAD_REF"   # which home / file / size / title
python3 "$S" summary "$THREAD_REF"                   # cwd, models, span, turns, compactions, tools
python3 "$S" turns   "$THREAD_REF" --width 160                                    # one block per turn: time, prompt, final answer
python3 "$S" turns   "$THREAD_REF" --since 2026-09-20 --last 15
python3 "$S" messages "$THREAD_REF" --turn 104,185 --full                         # full prompt + final answer of chosen turns
python3 "$S" messages "$THREAD_REF" --since 2026-09-24 --role user --full         # what the user asked recently
python3 "$S" search  "$THREAD_REF" 'PR #?\d+|self-?merge' --max 50                # regex over prompts/answers
python3 "$S" search  "$THREAD_REF" 'git status' --tools                          # also tool inputs/outputs (slower)
python3 "$S" tools   "$THREAD_REF" --commands --turn 185 --width 240              # every exec input in a turn
python3 "$S" export  "$THREAD_REF" --repo /path/to/repo               # Markdown transcript -> .local/codex-thread-dumps/<id>.md

A uuid prefix is enough as long as it is unique. --since/--until/--last/--turn share the turn numbering printed by turns. All commands stream the file; a 420 MB rollout takes ~1–3 s.

Recommended reading workflow for "了解前因后果"

1. locate + summary: confirm the right home/file, cwd, time span, model, number of turns and compactions.
2. turns over the whole thread: skim first-line prompts and final answers to build a timeline; note turn numbers of pivotal moments (decisions, merges, incidents, changes of direction).
3. messages --turn ... --full for those pivotal turns; add --commentary only when you need the agent's intermediate reasoning notes.
4. search for the specific entities you care about (PR numbers, file paths, people, project names, error strings). Use --tools when you need to know what commands actually ran.
5. If the thread will be referenced again, export it once into .local/codex-thread-dumps/ and read the Markdown; never copy the dump into Notes/ or any tracked file.

Privacy and boundaries

• Main threads usually contain career, company, legal, and personal content. Treat everything read as .local-only material: summarize into tracked files only after 脱敏, following AGENTS.md §4.A.10 and §5.
• Default export location is <repo>/.local/codex-thread-dumps/, which is git-ignored. Do not pass --out to a tracked path.
• Reasoning blobs are encrypted and are not decoded; tool outputs may contain tokens or internal URLs, so keep search --tools output out of tracked files.
• Never modify rollout files or the sqlite indexes; the script opens sqlite read-only.

Troubleshooting

• not found: the thread may belong to a home not under ~/.codex* (set CODEX_HOME=...), or the id may be a remote/cloud thread with no local rollout. The error prints the UUIDv7 timestamp so you can check that day's sessions/ directory manually.
• Multiple candidates: the sqlite hit is preferred over glob hits; a thread forked/moved between homes can appear twice. Check size and title.
• Turn without a user prompt: automation / heartbeat runs or turns whose prompt was only an attachment; use messages --commentary to see what happened.
• Stale numbers after the thread keeps running: turn indices are recomputed on every call, so re-run turns before citing a number.