codex-transcript-viewer 0.4.0__py3-none-any.whl

codex_transcript_viewer-0.4.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+codex_transcript_viewer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codex_transcript_viewer/cli.py,sha256=g9ebNO0zoTriV5ebogOI8s1n-2XCYoFopMS2Bu3nrsY,2639
+codex_transcript_viewer/formatting.py,sha256=mmT8EQajVvUgNdMwepgQf_Zg90VloPSZU_jk9k0Rbg8,718
+codex_transcript_viewer/html_builder.py,sha256=24H8XpjDPArF9veTTddws4_f1MjQnbere3FWqkUzRSk,30429
+codex_transcript_viewer/markdown.py,sha256=pHJn7j8hq43UDbwD-gS1aZG_OmrRoBRnSoQYiNUo-B4,5499
+codex_transcript_viewer/parser.py,sha256=lr7AKIkpT92EKoV9jTXtgKAHqo7EtvyHHax_ZL0W1uc,44308
+codex_transcript_viewer/style.css,sha256=fKmJtqx5xOixJld9Nlp5kQNmvQG4fRwhYh4V_K1Ji6M,11852
+codex_transcript_viewer/viewer.js,sha256=aLh0i31-TaIKJRrE2eQMbsT-qibsf4HfYAFVaXmWv5A,2108
+codex_transcript_viewer-0.4.0.dist-info/METADATA,sha256=jD4PrP9noZ5I7ETXIFcYJROs5zXv-LiY-DrqFZo8sp8,8154
+codex_transcript_viewer-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+codex_transcript_viewer-0.4.0.dist-info/entry_points.txt,sha256=PNnnEM5MX6WEtR_6EUlVSIwj4YHGIoyIXHzzuAvUw0Y,77
+codex_transcript_viewer-0.4.0.dist-info/licenses/LICENSE,sha256=5GGInVepX5KFapSam7Kgo2ruX3GQehi6Gl_RXw2APsU,1068
+codex_transcript_viewer-0.4.0.dist-info/RECORD,,

codex_transcript_viewer-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_transcript_viewer-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-transcript-viewer = codex_transcript_viewer.cli:main

codex_transcript_viewer-0.4.0.dist-info/licenses/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.