render-loop

A self-checking loop for developing this repo's exporter. It lets you see what the HTML actually renders (via a headless-Chrome screenshot you can open with the Read tool), fix the renderer, and re-validate — without leaving the session.

This skill is repo-local (.claude/skills/render-loop/) and not shareable: it hard-codes this repo's layout (skills/session-export/) and assumes Google Chrome + Node 18+.

The loop

When the user points at a rendering concern and a session (e.g. "the rendering of TaskGet looks like raw JSON, see session 2e875f45…"):

1. Locate & classify the session. A session id is a UUID. Claude sessions live under ~/.claude/projects/**/<uuid>.jsonl; Codex rollouts under ~/.codex/sessions/**/rollout-*<uuid>*.jsonl. If it's a Codex rollout, use --codex. You can pass a full path instead of an id.
2. Inspect the raw record first. Find the relevant tool_use / message in the jsonl to learn the exact input/result shape before changing code:

   grep -n '"name":"TaskGet"' <session.jsonl>   # or node one-liner to dump the block

3. Export + screenshot the card. From the repo root:

   .claude/skills/render-loop/render.sh <uuid-or-path> [--codex] --find "<text near the card>"

   --find text should be something visible in that card (a tool name, an arg, a phrase). It prints HTML: and PNG: paths. Read the PNG to view the current rendering. (Omit --find for a full-page capture, height-capped.)
4. Diagnose. Compare what you see against what the user wants. The renderer is skills/session-export/template.js (shared client renderer — tool cards live in the renderToolCall switch; entry/role logic in renderEntry/ renderRun). Parsing/normalization is export.js (Claude) and codex-export.js (Codex); shared redaction in redact.js.
5. Fix the JS (usually a case in the renderToolCall switch, or a helper).
6. Re-render & validate. Re-run the same render.sh … command, Read the new PNG, and confirm it matches the requested outcome. Iterate steps 4–6 until it's right. Also run the cheap sanity check after edits:

   node -e 'const h=require("./skills/session-export/template.js")();const m=h.match(/<script>([\s\S]*?)<\/script>\s*<\/body>/);new Function(m[1]);console.log("ok")'

   Then run the test suite (node --test test/). When a fix covers a new record or block shape, add it to the fixture in test/render.test.js (or test/payload.test.js for exporter-side changes), built with the helpers in test/helpers/fixtures.js — real shapes, synthetic content.
7. Report the change and offer to commit (template work currently lives on the codex-export branch).

Tools in this skill

• render.sh <session> [--codex] [--find "text"] [--index N] — export then screenshot in one step (most common entry point).
• shoot.js <file.html> [--find "text" | --selector css] [--index N] [--full] [--span N] [--no-expand] [--out png] — screenshot any already-exported HTML. --span N stretches the crop over the N siblings after the match (see a card in context, e.g. a compaction divider plus the turns after it). Drives Chrome over the DevTools Protocol with Node's built-in WebSocket (no npm deps); expands all collapsible cards (unless --no-expand, which shows the page as a reader first sees it), then crops to the matched element (or full page, capped at 4000px). Override the browser with CHROME_BIN.

Notes

• Exported HTML lands in the repo root (claude-session-* / codex-session-*, both gitignored); the PNG goes to $TMPDIR/render-loop.png. Both are scratch.
• --find matches the first card (.tool, .askq, .subagent, .context, .command, .entry) containing the text; use --index N to disambiguate.
• Self-improving: if the loop exposes a gap — shoot.js can't target what you need, a new card type isn't matchable, the diagnosis was slow — improve shoot.js / this SKILL.md as part of the task so the next loop is sharper.