trace

A local viewer for Claude Code and Codex session transcripts.

Both CLIs record everything they do as JSONL on disk — every prompt, every tool call, every byte of context. trace reads those files and renders the back-and-forth between you, the model, and the harness so you can actually see what happened.

Why

When something goes sideways in a long agentic session — wrong file edited, runaway tool loop, context blown through — the answer is in the transcript. The CLIs hide most of that under a chat UI. trace lays it out flat: turns, rounds, tool calls paired with their results, token usage per round, and the full prompt text the model actually saw.

It's a single Python file and a single HTML file. Zero dependencies, zero install.

Run it

git clone https://github.com/gpolaert/trace
cd trace
python3 server.py

Then open http://127.0.0.1:5050.

That's it. No pip install, no Node, no bundler — uses only the Python standard library.

Override the port with PORT=8080 python3 server.py.

What it shows

• Sessions list — every session under ~/.claude/projects/ and ~/.codex/sessions/ (plus ~/.codex/archived_sessions/), newest first, filterable by source or text.
• Turns and rounds — each user prompt opens a turn; each LLM round inside the turn is a separate group with its own token usage.
• Three actors — user, llm (assistant + thinking + tool_use), and harness (tool results, system events). Each is color-coded so the ping-pong is obvious.
• Tool call ↔ result pairing — every tool_use block has a → result link; the result block has a ← call link. Click either to jump to the other.
• Context window bar — for each round, a horizontal bar showing how much of the model's context window is filled with cache reads, cache writes, fresh input, and output.
• Session summary — model, total rounds, peak context, total output, billed input.
• Two render modes:
  • human — tools are humanized (Edit src/foo.ts with a colored diff, Bash $ ls -la, etc.), noise is hidden by default.
  • raw — every event as the harness wrote it, no humanization, nothing hidden.
• Filters — by actor (user / llm / harness), hide noise, hide thinking, collapse all, full-text search across event content.

State (mode, filters, expanded turns) persists in localStorage. Linking is via URL hash, so you can share a deep link to a specific session.

What it reads

Source	Path
Claude Code	~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
Codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
Codex (archived)	~/.codex/archived_sessions/rollout-*.jsonl

The server only serves files inside those three roots — path traversal is blocked.

Stack

• server.py — small http.server-based JSON API: lists sessions, returns a normalized event stream per session. Pure Python stdlib.
• index.html — single-file frontend, no build step, no framework.

Everything runs on 127.0.0.1. Nothing leaves your machine.

License

No license — public, no warranty, do whatever you want with it.