Codex Session Viewer

Local browser UI for following and inspecting Codex session JSONL files.

It reads Codex session files from ~/.codex/sessions/YYYY/MM/DD, renders each JSONL event into a readable stream, and provides an inspector for the underlying JSON structure.

Features

• Date and rollout file picker for Codex session logs.
• Live tailing through server-sent events.
• Readable event stream with filters for messages, tools, patches, errors, tokens, and context.
• Inspector tabs for summary, structured JSON tree, raw JSON, and related events.
• Expand all / collapse all controls for structured JSON.
• Resizable inspector pane and latest-top / latest-bottom ordering.
• Rich rendering for embedded JSON strings, Markdown-style text, and fenced code blocks in tool outputs.

Quick Start

npx codex-jsonl-viewer

The command prints the local URL to open:

http://127.0.0.1:8765

If port 8765 is already in use, the viewer automatically picks another available port and prints the actual URL.

The default session root is:

~/.codex/sessions

The page scans ~/.codex/sessions/YYYY/MM/DD, opens the most recently modified rollout-*.jsonl for the selected date, and tails appended JSONL lines through server-sent events.

To point the viewer at another sessions directory:

npx codex-jsonl-viewer --root /path/to/sessions

Other options:

npx codex-jsonl-viewer --port 9000
npx codex-jsonl-viewer --host 0.0.0.0
npx codex-jsonl-viewer --strict-port
npx codex-jsonl-viewer --open

Local Development

git clone https://github.com/willerhehehe/codex-jsonl-viewer.git
cd codex-jsonl-viewer
npm test
node bin/codex-jsonl-viewer.js

Requirements

• Node.js 18+
• No runtime npm dependencies

The repository also includes the original Python server as a fallback:

python3 server.py --port 8765

Verify

npm test

License

MIT