codex-transcript-viewer 0.4.0__tar.gz

codex_transcript_viewer-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.html
+CLAUDE.md

codex_transcript_viewer-0.4.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.4.0
+
+- The viewer is on PyPI: `uv tool install codex-transcript-viewer`, `pipx install codex-transcript-viewer`, or `uvx codex-transcript-viewer <session.jsonl>` to run it once.
+- Markdown tables render as tables, and links work. Web links open in a new tab; links to local files show their label, with the full path on hover. Bare `https://` addresses become links too.
+- Formatting no longer leaks into code: `**` inside a code block stays as written.
+- Sessions with malformed records no longer crash the parser. A fuzz of every record type turned up ten such spots.
+- Tests run on GitHub Actions for Python 3.11 through 3.14.
+
+## 0.3.0
+
+- Goals set with `/goal` show up, with their objective and each status change (complete, paused, blocked, out of budget). Codex logs the goal again after nearly every step, so only real changes are kept.
+- Generated images render, along with the prompt the model used. They count toward the `--max-image-mb` budget.
+- Hook messages, review start and result markers, and errors like a usage limit now appear. A review's findings are listed when no reply repeats them.
+- Reasoning headings no longer repeat. Newer models restate a turn's earlier headings every time they add one, which made about a quarter of the headings in recent sessions duplicates.
+- Record types that carry nothing to show (guardian approvals, subagent status, voice sessions, undo) are skipped quietly instead of being reported as unrecognized.
+
+## 0.2.2
+
+- 0.2.1 only fixed some of the doubled final answers. Older sessions also log a final answer without its memory citations or proposed plan, and those copies still showed as commentary. They're gone now, along with a doubled last message in older and plan-mode turns.
+- `scripts/audit_sessions.py` checks the viewer against real sessions for duplicated or missing entries, and `scripts/visual_review.py` screenshots one session per format. Run over about 8,500 sessions, both come back clean.
+
+## 0.2.1
+
+- Older sessions no longer show each final answer twice. Codex also logged final answers as commentary, and the viewer kept that copy.
+- The README screenshot shows the current viewer.
+
+## 0.2.0
+
+It's been a while since I updated this, and Codex has changed a lot in the meantime, so these fixes are long overdue. Newer sessions were missing most of what actually happened.
+
+- Prompts show up again. Codex 0.135 and later store them as `item_completed` records, which the viewer never read. Injected context like the environment block, AGENTS.md and skill text stays out. Thanks to joebb97, who opened #3, and to khoi for reporting it.
+- Tool calls now render in full, including code-mode `exec`, `apply_patch`, web searches and tool searches. The viewer colors each result by its real exit status. khoi contributed the name/value grid for tool parameters.
+- Tool screenshots render as images. The viewer used to dump them into the page as raw base64, which is why some pages hit 36 MB. It now embeds up to 25 MB of images per page. New flags: `--max-image-mb`, `--no-images`, `--max-output-chars`.
+- Duplicate messages no longer slip through when tool calls sit between the two copies, and the Answers filter finds every final answer.
+- Subagent threads show the agent and its parent thread. History copied from the parent sits in a collapsed block.
+- The viewer prints record types it doesn't recognize to stderr, so the next Codex format change shows up right away.
+
+## 0.1.0
+
+First release.

codex_transcript_viewer-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin Mason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_transcript_viewer-0.4.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: codex-transcript-viewer
+Version: 0.4.0
+Summary: Convert Codex CLI JSONL session transcripts to self-contained HTML viewers
+Project-URL: Homepage, https://github.com/masonc15/codex-transcript-viewer
+Project-URL: Issues, https://github.com/masonc15/codex-transcript-viewer/issues
+Project-URL: Changelog, https://github.com/masonc15/codex-transcript-viewer/blob/main/CHANGELOG.md
+Author: Colin Mason
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codex,html,jsonl,openai,transcript,viewer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# codex-transcript-viewer
+
+Converts Codex CLI JSONL session transcripts into single-file HTML viewers with sidebar navigation, search, and filtering. No external dependencies. Just open the `.html` in any browser.
+
+![Viewer showing a final answer with sidebar navigation and filters](https://raw.githubusercontent.com/masonc15/codex-transcript-viewer/main/docs/images/final-answer.png)
+
+See the [full demo](https://github.com/masonc15/codex-transcript-viewer/blob/main/docs/demo.md) for more screenshots and a walkthrough of every feature.
+
+## Install
+
+It's on PyPI, so install it with uv or pipx, or run it once without installing anything:
+
+```
+uv tool install codex-transcript-viewer
+pipx install codex-transcript-viewer
+uvx codex-transcript-viewer <session.jsonl>
+```
+
+For the latest unreleased changes, install straight from GitHub:
+
+```
+uv tool install git+https://github.com/masonc15/codex-transcript-viewer.git
+```
+
+To hack on it, clone the repo and install from the checkout instead, or run it without installing:
+
+```
+git clone https://github.com/masonc15/codex-transcript-viewer.git
+uv tool install ./codex-transcript-viewer
+uv run --directory ./codex-transcript-viewer codex-transcript-viewer <session.jsonl>
+```
+
+## Usage
+
+```
+codex-transcript-viewer <session.jsonl> [output.html]
+```
+
+If you omit the output path it writes `<input-stem>.html` in the current directory.
+
+Codex stores sessions as JSONL files under `~/.codex/sessions/`. Find one and point the tool at it:
+
+```
+codex-transcript-viewer ~/.codex/sessions/2026/02/18/rollout-2026-02-18T10-06-22-019c7149.jsonl
+open rollout-2026-02-18T10-06-22-019c7149.html
+```
+
+Images are embedded, so the page stays a single file. Images you attached to a prompt are always included, taken from the copy saved in the session log, since the original file is often a temp file that's long gone. Screenshots returned by tools are embedded until they add up to 25 MB, after which the rest show as placeholders and a note at the top says how many were left out. `--max-image-mb N` changes that budget (0 means no limit), and `--no-images` replaces every image with a labelled placeholder, which is handy when you want a small page or would rather not share what was on your screen.
+
+Tool output text is embedded in full. Codex already trims what the model sees to roughly 200K characters, so the viewer's own `--max-output-chars` guard (default 250,000, 0 to disable) only kicks in for something pathological.
+
+If the log contains record types the viewer doesn't know about, it says so on stderr after writing the page, which usually means Codex changed its format.
+
+## What the viewer shows
+
+The page has a sticky sidebar with a searchable event tree on the left and the transcript on the right. Your prompts get a green border, with any attached images shown as thumbnails you can click to enlarge. Final answers sit on a faint green background, commentary is italic with a muted border, and reasoning summaries are gray. Each tool call shows its command or arguments, and its result is colored by what actually happened: green when the exit code was 0, red when it failed, and neutral when the log doesn't record a status, so nothing looks successful by accident. Long outputs expand on click. Markdown in prompts and answers renders, tables included; web links open in a new tab, and links to local files show their full path on hover. Generated images show up as the result of their `image_generation` call, next to the prompt the model used. Turn starts, aborts, rollbacks and token counts show up as dim system lines.
+
+Some things Codex only sends to the model, so the viewer shows them as their own highlighted entries: the objective and status changes of a `/goal`, text a hook sent back (a rejected plan, for example), review start and result markers, and errors such as hitting a usage limit. A review's findings appear in full when no reply repeats them. Newer models repeat the turn's earlier reasoning headings each time they add one, so each heading is shown once, at the point it first appeared.
+
+The sidebar filters are Default, No tools, User, Answers and All. On narrow screens the sidebar tucks behind a hamburger menu.
+
+Subagent threads are labelled with the agent's name and parent thread. When a subagent was forked with its parent's conversation, the copied turns are folded into a collapsed block at the top instead of being shown as if the subagent wrote them.
+
+## Supported sessions
+
+Both session formats Codex has used are handled: the older one, where prompts are `user_message` events (seen through CLI 0.125), and the newer one, where they're `item_completed` records (CLI 0.135 and later). Tool calls cover plain function calls, code-mode `exec` and `apply_patch` custom tools, web searches, tool searches and image generation.
+
+## Limitations
+
+The transcript is an activity log, so rolled-back turns stay inline with a banner rather than disappearing. The filters hide sidebar entries, not the transcript itself.
+
+## Development
+
+Run the tests with `PYTHONPATH=src python3 -m unittest discover -s tests`. GitHub Actions runs them on Python 3.11 through 3.14 for every push and pull request, and also builds the package and converts a small session with the installed wheel. The tests use synthetic records, so they only cover the shapes someone thought to write down.
+
+Before a release, run `python3 scripts/audit_sessions.py` over your real sessions (it reads `~/.codex/sessions` and `~/.codex/archived_sessions` by default, or any paths you give it). For every session it checks that no text shows twice in a turn, that the visible prompts, messages and reasoning match what the raw records say should be there, and that every pair of record kinds sharing text is covered by a dedup rule. None of these compare against an earlier run of the viewer, so an old bug can't hide in the baseline. `--tar -` reads sessions from a tar stream, which is handy for an archive on another machine.
+
+Then run `uv run --with playwright python scripts/visual_review.py --from-audit report.json`, using the report from `audit_sessions.py --json report.json`. It renders one session per format, fails if two kinds of entry in the same role repeat each other, and saves sidebar screenshots to look over. Both scripts print session text, so keep their output out of the repository.
+
+Publishing a GitHub release uploads that version to PyPI. The release tag has to match the version in `pyproject.toml`.
+
+## Credits
+
+Inspired by the HTML session export in [pi](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent), a coding agent by [@badlogic](https://github.com/badlogic).
+
+## Project structure
+
+```
+src/codex_transcript_viewer/
+  parser.py       - JSONL parsing and event extraction
+  markdown.py     - lightweight markdown-to-HTML conversion
+  formatting.py   - timestamp formatting helpers
+  html_builder.py - assembles the final HTML from events
+  style.css       - all CSS for the viewer
+  viewer.js       - sidebar filtering and navigation
+  cli.py          - command-line entry point
+scripts/
+  audit_sessions.py - checks the parser against real sessions
+  visual_review.py  - renders sessions and screenshots the sidebar
+```

codex_transcript_viewer-0.4.0/README.md

@@ -0,0 +1,100 @@
+# codex-transcript-viewer
+
+Converts Codex CLI JSONL session transcripts into single-file HTML viewers with sidebar navigation, search, and filtering. No external dependencies. Just open the `.html` in any browser.
+
+![Viewer showing a final answer with sidebar navigation and filters](https://raw.githubusercontent.com/masonc15/codex-transcript-viewer/main/docs/images/final-answer.png)
+
+See the [full demo](https://github.com/masonc15/codex-transcript-viewer/blob/main/docs/demo.md) for more screenshots and a walkthrough of every feature.
+
+## Install
+
+It's on PyPI, so install it with uv or pipx, or run it once without installing anything:
+
+```
+uv tool install codex-transcript-viewer
+pipx install codex-transcript-viewer
+uvx codex-transcript-viewer <session.jsonl>
+```
+
+For the latest unreleased changes, install straight from GitHub:
+
+```
+uv tool install git+https://github.com/masonc15/codex-transcript-viewer.git
+```
+
+To hack on it, clone the repo and install from the checkout instead, or run it without installing:
+
+```
+git clone https://github.com/masonc15/codex-transcript-viewer.git
+uv tool install ./codex-transcript-viewer
+uv run --directory ./codex-transcript-viewer codex-transcript-viewer <session.jsonl>
+```
+
+## Usage
+
+```
+codex-transcript-viewer <session.jsonl> [output.html]
+```
+
+If you omit the output path it writes `<input-stem>.html` in the current directory.
+
+Codex stores sessions as JSONL files under `~/.codex/sessions/`. Find one and point the tool at it:
+
+```
+codex-transcript-viewer ~/.codex/sessions/2026/02/18/rollout-2026-02-18T10-06-22-019c7149.jsonl
+open rollout-2026-02-18T10-06-22-019c7149.html
+```
+
+Images are embedded, so the page stays a single file. Images you attached to a prompt are always included, taken from the copy saved in the session log, since the original file is often a temp file that's long gone. Screenshots returned by tools are embedded until they add up to 25 MB, after which the rest show as placeholders and a note at the top says how many were left out. `--max-image-mb N` changes that budget (0 means no limit), and `--no-images` replaces every image with a labelled placeholder, which is handy when you want a small page or would rather not share what was on your screen.
+
+Tool output text is embedded in full. Codex already trims what the model sees to roughly 200K characters, so the viewer's own `--max-output-chars` guard (default 250,000, 0 to disable) only kicks in for something pathological.
+
+If the log contains record types the viewer doesn't know about, it says so on stderr after writing the page, which usually means Codex changed its format.
+
+## What the viewer shows
+
+The page has a sticky sidebar with a searchable event tree on the left and the transcript on the right. Your prompts get a green border, with any attached images shown as thumbnails you can click to enlarge. Final answers sit on a faint green background, commentary is italic with a muted border, and reasoning summaries are gray. Each tool call shows its command or arguments, and its result is colored by what actually happened: green when the exit code was 0, red when it failed, and neutral when the log doesn't record a status, so nothing looks successful by accident. Long outputs expand on click. Markdown in prompts and answers renders, tables included; web links open in a new tab, and links to local files show their full path on hover. Generated images show up as the result of their `image_generation` call, next to the prompt the model used. Turn starts, aborts, rollbacks and token counts show up as dim system lines.
+
+Some things Codex only sends to the model, so the viewer shows them as their own highlighted entries: the objective and status changes of a `/goal`, text a hook sent back (a rejected plan, for example), review start and result markers, and errors such as hitting a usage limit. A review's findings appear in full when no reply repeats them. Newer models repeat the turn's earlier reasoning headings each time they add one, so each heading is shown once, at the point it first appeared.
+
+The sidebar filters are Default, No tools, User, Answers and All. On narrow screens the sidebar tucks behind a hamburger menu.
+
+Subagent threads are labelled with the agent's name and parent thread. When a subagent was forked with its parent's conversation, the copied turns are folded into a collapsed block at the top instead of being shown as if the subagent wrote them.
+
+## Supported sessions
+
+Both session formats Codex has used are handled: the older one, where prompts are `user_message` events (seen through CLI 0.125), and the newer one, where they're `item_completed` records (CLI 0.135 and later). Tool calls cover plain function calls, code-mode `exec` and `apply_patch` custom tools, web searches, tool searches and image generation.
+
+## Limitations
+
+The transcript is an activity log, so rolled-back turns stay inline with a banner rather than disappearing. The filters hide sidebar entries, not the transcript itself.
+
+## Development
+
+Run the tests with `PYTHONPATH=src python3 -m unittest discover -s tests`. GitHub Actions runs them on Python 3.11 through 3.14 for every push and pull request, and also builds the package and converts a small session with the installed wheel. The tests use synthetic records, so they only cover the shapes someone thought to write down.
+
+Before a release, run `python3 scripts/audit_sessions.py` over your real sessions (it reads `~/.codex/sessions` and `~/.codex/archived_sessions` by default, or any paths you give it). For every session it checks that no text shows twice in a turn, that the visible prompts, messages and reasoning match what the raw records say should be there, and that every pair of record kinds sharing text is covered by a dedup rule. None of these compare against an earlier run of the viewer, so an old bug can't hide in the baseline. `--tar -` reads sessions from a tar stream, which is handy for an archive on another machine.
+
+Then run `uv run --with playwright python scripts/visual_review.py --from-audit report.json`, using the report from `audit_sessions.py --json report.json`. It renders one session per format, fails if two kinds of entry in the same role repeat each other, and saves sidebar screenshots to look over. Both scripts print session text, so keep their output out of the repository.
+
+Publishing a GitHub release uploads that version to PyPI. The release tag has to match the version in `pyproject.toml`.
+
+## Credits
+
+Inspired by the HTML session export in [pi](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent), a coding agent by [@badlogic](https://github.com/badlogic).
+
+## Project structure
+
+```
+src/codex_transcript_viewer/
+  parser.py       - JSONL parsing and event extraction
+  markdown.py     - lightweight markdown-to-HTML conversion
+  formatting.py   - timestamp formatting helpers
+  html_builder.py - assembles the final HTML from events
+  style.css       - all CSS for the viewer
+  viewer.js       - sidebar filtering and navigation
+  cli.py          - command-line entry point
+scripts/
+  audit_sessions.py - checks the parser against real sessions
+  visual_review.py  - renders sessions and screenshots the sidebar
+```

codex_transcript_viewer-0.4.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "codex-transcript-viewer"
+version = "0.4.0"
+description = "Convert Codex CLI JSONL session transcripts to self-contained HTML viewers"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Colin Mason" }]
+keywords = ["codex", "openai", "transcript", "jsonl", "html", "viewer"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/masonc15/codex-transcript-viewer"
+Issues = "https://github.com/masonc15/codex-transcript-viewer/issues"
+Changelog = "https://github.com/masonc15/codex-transcript-viewer/blob/main/CHANGELOG.md"
+
+[project.scripts]
+codex-transcript-viewer = "codex_transcript_viewer.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_transcript_viewer"]
+
+# List the sdist contents so local-only files (plans, notes) never ship.
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "scripts", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]