[Ark0N]

Story Mode: a Claude session drawn as comic pages, live

Watching an agent work means reading a terminal that scrolls past faster than anyone reads. That works for the person who wrote the prompt and knows the code, and shuts out everyone else: a manager, a designer, a new teammate, someone glancing at a phone. Story Mode adds a second way to watch a Claude Code session. Each turn (one prompt and everything Claude did for it) becomes one comic page: panels for reading code, making a plan, calling in helpers, editing files, running tests (POW! or KRAK!), asking you something and saving the work, each with a caption anyone can follow.

It is opt-in and off by default: App Settings → Header buttons → Story Mode (per device). On a phone it opens from Session Options (same setting). It reads the session's own Claude transcript through two new, experimental, read-only routes and draws in a full-window overlay; it adds no setting that changes how sessions run.

One change reaches beyond Story Mode: the server now also checks prompts sent by the browser's composers (Story Mode's prompt bar and the phone's Compose sheet) and presses Enter again while Claude Code is still ignoring it. See The Enter check below; it is the part of this PR that touches every prompt.

What you see

• Three reading levels in the bar: Simple (plain words built from fixed templates, no paths, commands or jargon), Advanced (the story with file names) and Director's cut (every step and tool, with a list of every event of the turn beside the page). Director's cut is the default for now; a reader's pick is kept per device.
• Everything is clickable. A file card opens Codeman's file viewer. The code page shows the diff of Claude's edits (Edit and Write calls exactly, with line numbers; a file written through the shell with its new lines; a file a script rewrote, listed without lines). A test board shows the output with clickable file:line links. A helper shows what Claude asked it, what it answered and every step it took, read from the helper's own transcript (live while a background helper works).
• Live. A turn that is still running redraws as Claude works: new panels ink in where blue-pencil roughs stood, and the event list follows the turn with a smooth glide (scroll up and it stops, with a pill for new rows).
• Fills the window. Panel rows are sized to the window (with a floor and per-row caps), text scales with them, and a panel whose caption or balloon needs room grows instead of covering its art or Claude's face.
• A prompt bar under the page holds the turn picker and a field that sends Claude your next prompt (Enter sends, Shift+Enter adds a line), so you can keep a session going without leaving the comic. It sends through the same function as the phone's Compose sheet.
• Save image downloads the page as a PNG to share with someone who never opens a terminal.

How it works

Server (src/story-mode.ts pure; src/story-reader.ts IO; src/web/routes/story-routes.ts):

• GET /api/sessions/:id/story[?turn=<id>] draws one turn; GET /api/sessions/:id/story/helpers/:agentId draws one helper from its own transcript (<conversation>/subagents/agent-<agentId>.jsonl, the id checked against a strict charset). Both are documented in docs/api-reference.md as experimental.
• Both read the session's OWN Claude transcript, never a path from the request: the path the Claude hook reported, only when it really lies (symlinks resolved) in a Claude projects folder (the session's relocated CLAUDE_CONFIG_DIR, or the server's), else a lookup by conversation id, then Codeman id. Story Mode is the first route that sends transcript content to the browser, which is why the hook path is confined. Only a regular file is read, through one non-blocking handle, so a FIFO in its place fails at once instead of pinning a libuv worker. Only the tail is read (8 MB, widened in steps to 64 MB while that tail holds no prompt to start the turn).
• Three pure stages turn it into a page. Reduce each JSONL line to compact entries: this is where size is shed (Read results' contents, Edit/Write originalFile and images never leave this step; outputs keep a bounded tail; hunks are capped). Join each tool call with its result and split entries into turns (a background helper stays "running" until its <task-notification> arrives in a later turn, then its answer is joined back). Group a turn's events into at most 12 panels with captions for each level.
• Grouping is what makes it read like a story rather than a log. Across every Claude transcript on the machine this was built on (1,309 files, 3,856 turns, 44,008 tool calls), Bash is 87% of all tool calls, so a Bash call is sorted by what its command does (looking, testing, building, editing, saving, running), not by its tool name: one-liners are split at &&, ||, ;, | and newlines outside quotes, here-document bodies are skipped, wrappers (timeout 60, env assignments, git -c) are stripped, and the strongest part wins. Calls in a row with the same intent share a panel; fix → test → fix → test folds into one "loop" panel; a long turn folds its quieter panels into a montage.
• The route never adopts a conversation id or persists anything. It answers { supported: false, reason } for a CLI that writes no Claude transcript (registry capabilities.transcript, never a mode check) and for remote or Docker sessions, whose transcript is not on this host.
• Responses carry a weak ETag; an unchanged transcript is a 304 decided from a stat, before anything is read.

Frontend (src/web/public/story-mode.js, story-mode.css): a full-screen overlay with a small canvas frame engine (each scene is a pure function of its frame number). Only new panels animate in; prefers-reduced-motion draws every panel finished.

• Untrusted text: everything on the page comes from the agent and is written with textContent only, inside data-i18n-skip containers. On the server every helper that matches transcript text runs in linear time on crafted input (an agent can be prompt-injected, and one regex call blocks the whole server): timing each helper at its input cap found five shapes that were quadratic or worse (up to 29 s on 1 MB); they use indexOf scans now, and a test times them.
• Files open through the existing openFilePreview(), which already handles workspace confinement, outside paths and remote hosts.
• Keyboard: canvas click regions are real, labelled buttons; Tab stays inside the overlay; Escape closes one layer per press (a file preview opened from a panel, then the drawer, then the overlay).
• Live refresh: the transcript tool events and the stop and prompt-submitted hooks (extra addListeners in connectSSE), plus a 4 s poll while a turn runs; one request in flight, debounced.
• Fonts: two OFL comic fonts (Bowlby One SC, Patrick Hand SC; Latin subsets, about 23 KB each), self-hosted because the CSP is font-src 'self'; licenses in fonts/LICENSE-story-fonts.txt.

Performance, measured on this machine: a cold read of a 110 MB transcript takes 50 ms with a longest event-loop stall of 10 ms; a cached read about 0.1 ms; building a page 1 to 7 ms. A page carries at most 120,000 characters of outputs, hunks and helper texts (newest first); the largest live page in a sweep of every local transcript is 74 KB gzipped. Panels repaint by need (30 fps entering, 15 fps for a running turn's newest panel, 6 fps settled, stopped after 20 s): five panels on a 2x screen went from 81% of a core to 2.4% once settled. Stepping through 40 turns went from 46 long tasks to 1 (enough before to make the app drop the terminal's WebGL renderer).

The Enter check, also outside Story Mode

Claude Code 2.1.277+ ignores Enter for the first 30 to 50 s after its composer paints while still taking the typed text. The server already handles that for API prompts: SubmitVerifier (src/session-submit-verifier.ts) reads the pane on a 2 s to 60 s schedule and presses Enter again while the composer still holds the prompt. The browser's composers never send a text\r pair, though: they write one bracketed paste and a bare Enter about 120 ms later (Codex drops a key that shares a read with a paste), so that check never ran for them.

PastedPromptWatch pairs those two writes back up (in Session.write() for the WebSocket, and in writeViaMux() for the POST fallback) and arms the same check. Nothing may come between the two: any other write breaks the pair, and typed keystrokes plus Enter arm nothing. Changes to the check itself, which reach every API prompt too:

• A prompt under 24 characters must now match the composer whole, so a one-word answer cannot read a dialog's highlighted row (❯ 1. Yes) as itself.
• A multi-line prompt is recognised in both shapes Claude Code draws: inline (a short first line plus its continuation lines) and the [Pasted text #1 +3 lines] stand-in, which counts only when its line count is the prompt's own. Since master now pastes a multi-line API prompt with its line breaks, _verifySubmitted() keeps them for that count.
• A paste made in the browser cancels any pending re-press, so Enter never submits the user's own paste.
• Codex's [Pasted Content N chars] stand-in is still not matched (not measured).

How it was proven: the defect did not reproduce on Claude Code 2.1.303 (5 sends 0.3 to 1 s after the composer painted, all taken on the first Enter), so this is a safety net. A stand-in claude that draws Claude's composer and ignores Enter for its first 25 s reproduced it: sent from the real Story prompt bar in a browser about 5 s after start, the old build left the prompt stuck for 45 s on both the WebSocket and the POST fallback; the new build pressed Enter again at 2, 5, 10, 15 and 20 s and the prompt went through once at 25 s, the first moment it could. On real Claude Code the new build caused no extra Enter, and left alone for 65 s both text typed into Claude's composer after a send and a 4-line paste dropped into the pane.

Reviewing the diff

58 files, +20,294 / -27, but most of it is not code to read line by line:

Part	Lines	What to do with it
test/fixtures/story-corpus/ (11 recorded sessions + their pinned pages)	3,806	Skim one .expected.json to see what a page looks like
Tests (test/story-*.ts, test/routes/story-routes.test.ts, verifier tests)	5,419	Read alongside the code they cover
Font license text (the two .woff2 files are binary)	193	Nothing to review
Docs + changeset	62	Prose
New frontend: story-mode.js, story-mode.css	6,208	Self-contained overlay
New server: story-mode.ts, story-reader.ts, story-routes.ts, types/story.ts	4,361	The core worth review
Edits to existing files	245 / -23 in 14 files	Read all of these

The edits to existing files are the ones that can affect anything else:

• src/session-submit-verifier.ts (+91/-12) and src/session.ts (+36/-6): the Enter check.
• src/utils/claude-transcript.ts (+64): finds a recovered session's (restored-<id>) transcript, the same recovery last-response makes.
• app.js (+21): the SSE listeners for live refresh and a Story Mode entry in Shortcuts (no default chord).
• index.html (+7/-2): the header button, the Session Options button, the settings chip, the script and stylesheet.
• One-line registrations: the route and type barrels, server.ts, schemas.ts (showStoryButton, next to showResponseViewer), settings-ui.js (per-device key and visibility), i18n.js (the setting's zh-CN label), config/test-suites.ts (the browser test).
• styles.css/mobile.css: the header button's hidden marker, kept off phones like the other new header controls.

The branch was built over several days and is 109 commits, including two merges of master (Merge master into feat/story-mode). The first resolved additive registrations plus session.ts, where master's public claudeConfigDir() replaced the branch's getter and the composer pairing moved into master's guarded _writeViaMuxNow; the second picked up master's frontend dead-code cleanup (one line in the src/web/CLAUDE.md z-index list). Squash-merging is fine.

Risk

• The Enter check is the one change outside the feature: a wrong match would press Enter into someone's composer. The guards: it acts only while the LAST composer line holds the prompt (whole for short prompts), any other text or no composer line ends it, a newer write or paste cancels it, and the composer pairing accepts only a paste immediately followed by a bare Enter within 10 s. It was proven against a stand-in CLI because current Claude Code no longer shows the defect.
• Transcript content goes to the browser for the first time. The read is confined to the session's own transcript inside a Claude projects folder, ownership-checked like every session route, and every string is rendered as text. The terminal card drawn on the canvas (which goes into a saved image) leaves out lines that look like secrets and masks addresses and long token-like strings, but that masking is a heuristic.
• Wording heuristics (when a page says "Done, with a catch", "as you asked", "starts a git repository") were precision-checked by sweeping all local transcripts, but they are heuristics on another program's transcript format. test/story-corpus.test.ts pins every page of the 11 recorded sessions, so a change in Claude Code's format or in the wording shows up as a diff.

Reviewed against real sessions

Review agents started real Claude Code workers on an isolated Codeman instance, gave each a small program to build, watched Story Mode draw it live, then checked every panel against the transcript and the files on disk. Later rounds had cold readers (someone who has never written code, an engineering manager skimming, a new teammate, a fact-checker) read only the comic, write down what they believed happened, and only then compare with the recordings. Every finding is fixed with a test. Eleven of those transcripts, sanitized (paths, user names and emails rewritten, Read contents left out), are the regression corpus.

The twelve rounds and what each found

• Round 1 (a Python CLI with pytest, a pomodoro page with node:test, a bash script with a background helper): a commit or test run past the first 400 characters of a long one-liner was classified from the display clip; a failing pytest run piped through tail drew as a pass; a background helper drew as finished with Claude Code's internal launch notes as its answer; logging into scratch files drew as code changes; balloons covered the art on narrow panels.
• Round 2 (a prompt added mid-turn, background helpers then an interrupt, a question then failing tests first then a push): a prompt added mid-turn is a queued_command attachment with no user line; some sessions never write turn_duration; helpers can be teammates reporting in <teammate-message>s; files are often written through here-documents. Also commits vanishing into montages, a red test run tagged "ok", a failed push drawn as SAVED, and a full page reshuffling while live.
• Round 3 (a written plan with a dry run, /compact then plan mode, keyboard-only use, image export, skins, a non-Claude session): a typed /compact drawn as two turns, a local command's turn left "working", the plan file under ~/.claude/plans/ counted as a code change, Tab walking out of the overlay.
• Round 4 (a 110 MB real session; local commands and the advisor live): a scheduled run drawn inside the /compact turn before it, a turn with seven added prompts drawing past the 12-panel cap, and 46 long tasks when stepping through 40 turns.
• Round 5 (a non-technical cold reader; a phone with touch): a push followed by a failing step drawn as a failed push, a formatter's preview read as a failure, a blocked command ending in confetti; Save image exporting blank panels below the fold, small tap targets, a drawer cutting through the bar.
• Round 6 (keyboard, screen reader, contrast, reduced motion, 200% zoom): a commit then a push counted as two commits, an open drawer rebuilt on every refresh and not tied to its turn, focus dropped when Previous/Next disabled itself, text contrast down to 1.42:1 in the light skin.
• Round 7 (security and fresh-eyes code review): quadratic cache eviction (a 2 s stall), a FIFO in place of a transcript pinning libuv workers, the hook path trusted for content, a hung request wedging the view across a reopen.
• Rounds 8 to 12 (cold readers and fact-checkers): the closing panel kept only Claude's first sentences while what readers needed was further in ("the page will not work when double-clicked", a helper's tests that never ran). Claude's last words now keep one sentence of each kind (a problem left, a question or offer, how to use the result, something not done, a failed step), the final panel says "Done, with a catch/note/question", a failure you asked for reads "fails on purpose, as you asked", a save no prompt asked for gets a small line, a push to a folder on this computer says so, a stop names the step and the open to-do items. Each round's fact-checker verified every guessed claim (each new repository, each local copy, each "as you asked") against the recordings.

Known limits

• Story Mode cannot tell whether Claude saved the work because a project rule asked or on its own; it says "a save your prompt here did not ask for" in a small line, never as a fault.
• A stop names the step Claude was on and the open items of its to-do list; when the plan lives only in your prompt, what is left is not listed.
• Files a command makes as test data count as changed files, and only the ones it names literally are listed.

Not in this PR

• Other CLIs. Codex, OMP and DeepSeek have transcripts of their own; the page shape is CLI-neutral, but only the Claude reader exists.
• zh-CN beyond the setting's label: the comic text is generated in English on the server, and translating only the chrome would leave a mixed page.
• Accept/reject buttons on single changes (a new way to write files, so it needs a decision first).
• Outputs on demand: a long live turn still sends its newest outputs with every changed page (at most 74 KB gzipped); a per-event route would make that a few KB at the cost of new API surface.

Testing

• test/story-mode.test.ts (165 tests): Bash classification (segments, wrappers, probes, redirects into scratch, here-documents, scripts fed by one), test-count parsing (vitest, jest, pytest incl. all-failing and collection errors, mocha, cargo, node:test), the reducer (no file contents or originals survive, hunk counts, output tails, skipped meta/compact/sidechain/local-command entries, task notifications, interrupts, background commands), turns (queued prompts, partial turns, failed and pending calls, background helpers joined back), pages (captions at all three levels, balloons, loop marks, montage capping, the text budget, live panels), the wording rules behind every caption and title, and crafted inputs timed at sizes where the old code took seconds.
• test/routes/story-routes.test.ts (25 tests): the newest page and an older turn by id; unsupported CLI, remote and Docker sessions; another user's session in multi-user mode; no transcript, a hook path outside the projects folder, a symlink out of it, a FIFO transcript and a FIFO meta file; a live turn growing between reads; a half-written last line, a replaced file, concurrent reads; 304 on an unchanged page; a turn larger than the first tail; the helper route.
• test/story-mode-ui.test.ts (77 tests, JSDOM with a fake canvas): the real module draws every scene in every panel shape, opens every drawer, follows a live page, switches levels, sends from the prompt bar, keeps Escape and Tab order, and pins the fixes from the review rounds.
• test/story-corpus.test.ts (39 tests): every page of the eleven recorded sessions, at every level; test/story-plain-words.ts checks that no Simple caption carries a path, command or jargon.
• test/session-submit-verifier.test.ts (28 tests): the paste shapes Claude Code draws, the paste pairing, and a session-level suite for the WebSocket and POST fallback sends, a taken prompt, a newer paste cancelling, typing arming nothing, and a multi-line API prompt shown as the stand-in.
• test/story-mode.browser.test.ts (6 tests, browser suite, not in the gate): a real server and Chromium; a running turn redraws live from real SSE events, the diff drawer, Escape order, Session Options → Story, Save image downloads a real PNG, no sideways scroll at 400 px, and panels that grow instead of covering or cutting off their words. Passes on the merged branch.
• On the branch with master merged in: typecheck, lint, format:check, check:frontend-syntax, check:public-assets, check:browser-excludes, master's new check:frontend-dead and knip pass, and the full npm test gate: 17,440 passed, 13 skipped, 0 failed (on the first merge; CI runs it on the current head).