codex-session-reader

A skill for read-only viewing of a single Codex session/thread, which under the hood reads via the codex app-server official interface.

By default outputs all turns; if you only want to see a portion, you can use --turns to pass a 0-based, Python-like slice expression.

Quick start

cd skills/codex-session-reader
./scripts/codex_session_reader.py read <thread-id>

Environment notes

This skill depends on the codex command being directly executable on the local machine, and under the hood it calls codex app-server。
For the current Codex environment, tool execution may not follow the interactive fish, and may fall back to zsh -lc。
So only setting fish in PNPM_HOME is not enough; you must make sure the zsh at PATH startup also contains PNPM_HOME, otherwise it will report "not found codex”。
It is recommended to set both in the zsh config following the official pnpm style:

export PNPM_HOME="$HOME/Library/pnpm"
case ":$PATH:" in
  *":$PNPM_HOME:"*) ;;
  *) export PATH="$PNPM_HOME:$PATH" ;;
esac

When to use

The user asks to view a certain Codex thread/session.
The user provides a thread id and wants to read the full context.
You need to convert the content of a certain Codex session into Markdown that can be further summarized or analyzed.

Common commands

./scripts/codex_session_reader.py read <thread-id>                    # 读取完整 thread
./scripts/codex_session_reader.py read <thread-id> --preview-only     # 只看 preview 和元信息
./scripts/codex_session_reader.py read <thread-id> --turns :5         # 前 5 个 turns
./scripts/codex_session_reader.py read <thread-id> --turns -5:        # 后 5 个 turns
./scripts/codex_session_reader.py read <thread-id> --turns 10:-1      # 从第 10 个到倒数第 1 个之前
./scripts/codex_session_reader.py read <thread-id> --turns 13         # 只看第 13 个 turn
./scripts/codex_session_reader.py read <thread-id> --turns 13:15      # 读取第 13 到第 14 个 turns
./scripts/codex_session_reader.py read <thread-id> --format json      # 输出 JSON

Output conventions

By default outputs markdown, suitable for continuing to hand to Codex for reading or summarization.
By default outputs all turns.
--format json Outputs the structured result returned by app-server, convenient for script processing.
If range trimming occurs, the JSON will additionally include a truncated field explaining which segment is actually output.
--turns does not support step;1:10:2 expressions like this will report an error.