Codex Log Reader

Bundled commands use $PLUGIN_ROOT ($env:PLUGIN_ROOT in PowerShell; same path suffix) for the plugin root. Set it once: use the host's plugin-root variable when defined (Claude Code: PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"), otherwise the absolute path of this plugin's root directory.

Use this skill to find the smallest useful slice of Codex logs before opening raw JSONL. Session logs are useful evidence, but they can contain user prompts, tool I/O, environment fragments, URLs, and secrets.

For deeper log locations, JSONL shape, manual jq fallbacks, and safety rules, read $PLUGIN_ROOT/references/log-reader-safety.md.

Fast Path

Primary tool:

python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" --help

Decision tree:

1. If the user provides CODEX_THREAD_ID, locate exactly:

   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" find --thread-id <thread-id>

1. If the user gives a project path, issue key, app name, or vague "find that run", rank likely sessions:

   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" find --cwd /path/to/project --query "ISSUE-123" --since-days 14 --limit 10

1. Summarize the best candidate without raw output:

   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" brief /path/to/rollout.jsonl

1. Reconstruct what happened with compact views:

   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" timeline /path/to/rollout.jsonl --tail 80
   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" messages /path/to/rollout.jsonl --tail 40
   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" commands /path/to/rollout.jsonl --tool exec_command --tail 80

1. Search narrowly, then open only the needed line window:

   python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" search "Traceback" /path/to/rollout.jsonl --limit 20
   nl -ba /path/to/rollout.jsonl | sed -n '120,150p'

Only use raw nl, sed, or jq after the helper has identified a path and line range.

Health Checks

Use doctor when the Codex UI cannot see a thread, resume behaves strangely, or a log may be too large:

python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" doctor --since-days 30 --limit 50
python3 "$PLUGIN_ROOT/scripts/codex_log_reader.py" doctor /path/to/rollout.jsonl

It checks malformed JSONL lines, very large rollout files, archived placement, and loose Unix permissions. Treat findings as evidence for diagnosis, not as permission to delete, move, chmod, or edit logs without explicit approval.

Safety Rules

• Do not paste raw rollout lines unless the user explicitly needs that exact excerpt and you checked it for secrets.
• Default to snippets, line numbers, counts, tool names, cwd, timestamps, and summarized commands.
• Never expose raw secrets, cookies, Authorization headers, API keys, private keys, seed phrases, wallet material, .env values, or credential-bearing history.
• Build/tool *-state.json files may contain full environment dumps; do not treat them as safe logs.
• If searching for credentials, report indicators and line numbers only, not matched secret values.

Tool Validation

The helper has local tests:

python3 -m unittest discover -s ../../tests -q