Six months of defaulting to HTML for plans, reviews, and diagrams. What actually changed in the loop, what broke when I tried to round-trip edits, and the one carve-out I still reach for when a reply is genuinely three sentences long.
In April, Thariq, who works on the Claude Code team: published The Unreasonable Effectiveness of HTML, arguing that HTML, not markdown, should be the default canvas between you and your agent. Richer, denser, shareable, drawable. Days later Kurtis Redux answered with The Unreasonable Ineffectiveness of HTML, calling the whole move a step backward: security risk, infra dependency, token cost, hostile source, and one objection that actually lands, review and version control.
I am not a neutral party. I have been defaulting to HTML for six months, across a real operation: a quarry, a fleet, a safety binder, people who do not have a markdown renderer and never will. So this is a field report, not a thesis. Thariq is mostly right about why. Redux is mostly wrong about the reasons, except the one he is completely right about, and that Thariq waves off. This is the answer I owe both of them.
Before, the work came back as markdown I skimmed in the terminal. A maintenance plan, a compliance summary, a pre-op checklist roll-up, all of it a wall of hyphens and pipe characters I'd squint at, half-render in my head, and usually re-ask for. Then I changed one line in how I ask: give me a single self-contained HTML file I can double-click. Three things changed, and none of them were cosmetic.
Density got honest. A forty-row asset-compliance matrix is a table. In markdown it is either a table that overflows the terminal and wraps into nonsense, or it is "summarized" down to the six rows that fit, which means the agent decided what I get to see. As real HTML it is the whole matrix, sortable in my head, color-coded by expiry. The information stopped being negotiated down to what the format could carry.
One artifact, one recipient. The safety officer does not have a markdown renderer. The fleet supervisor reads PDFs on a phone in a truck. When the output is an HTML file, I send the file. Nobody installs anything, nobody sees raw |---|---|, nobody asks me to "export it properly." The artifact is already in the format the human can open.
The agent stopped fighting its own diagrams. A renewal timeline is a timeline. Asked for markdown, the model reaches for a fenced Mermaid block and hopes my viewer renders it, or it draws a horizontal bar out of === and >. Asked for HTML, it draws an SVG. It turns out the model is good at drawing when you let it use the tool for drawing.
This is Thariq's case, and I am not going to re-litigate it, he made it better than I will. cf. Thariq, "The Unreasonable Effectiveness of HTML" What I want to do is the part he and Redux both skipped: say honestly where it costs, and answer the objection that survived contact with my actual work.
Markdown is wonderful for the things markdown is for: prose with a few headings, a short list, a code block, a link. I write these field notes in it. The trouble is not markdown. The trouble is the markdown your agent emits when the content it has does not fit the format it was told to use, and then it spends tokens, and your patience, fighting the gap.
You have seen the symptoms. A status dashboard rendered as ASCII art with misaligned columns. A nested table: a table inside a list item inside another table: that renders in exactly one of your tools and garbles in the other three. A code fence inside a bullet inside a numbered list, with the indentation off by two spaces so half of it falls out of the block. A diagram approximated with ┌──┐ and │ that looked fine in the model's monospace imagination and looks like a ransom note in your chat client.
Markdown is a fine format for the things markdown is for. The fight starts when your agent uses it for the things it isn't, and then has to wrestle the syntax into a shape it was never meant to hold.The tell, when you read the raw source because the rendered version is worse
There is a clean tell for when the format has failed: you find yourself reading the raw markdown source because the rendered version is somehow worse. When that happens, the format isn't carrying the content, you are, in your head, doing the rendering the format couldn't. That is the moment the agent was fighting, and lost, and handed you the fight.
Redux frames this as a virtue. He says source readability is the readability that matters, that knowledge workers live in editors and should read the source. Sometimes, for prose, for code, yes. But "the source is more readable than the render" is not a property you want in a compliance matrix. It is a confession that the render failed.
If I am going to ask you to take HTML seriously, I owe you the failure mode, because it is real and Thariq mostly skips it. Generating HTML is cheap and good. Editing it by hand is miserable. The first time I wanted to change two numbers in a generated report myself, not ask the agent, just fix a typo · I was spelunking through inline styles to find the cell, and I understood exactly what Redux meant when he called hand-editing HTML hostile to human eyes. On the raw source, he is right.
The deeper version is the round-trip: I edit the artifact, hand it back to the agent, it edits again, returns it to me. Every hop, the human is reading and writing a format optimized for neither. In markdown that loop is painless: the diff is legible, the edit is obvious. In HTML the loop grinds. This is the genuine cost, and it is not small, and "context windows are huge now" does not make it go away, because the bottleneck is the human in the loop, not the tokens.
None of these are reasons to abandon HTML. They are the reasons you do not make it the format for everything, which is the mistake §06 is about, in the other direction.
Strip away the five weaker objections and one remains standing: review and version control. Redux puts it sharply, "if it can't be reviewed, it's a toy", and he is correct. For serious work, review is non-negotiable, and an HTML diff is noisy in a way that makes human review harder, not easier. Thariq concedes this is "the biggest downside" and then shrugs it off. The shrug is the actual problem with his essay. You do not get to name the load-bearing objection and then walk past it.
So Redux wins the point. Where he overreaches is in what he does with it: he bundles the real objection together with five weak ones and uses the bundle to reject HTML wholesale. That is the move I want to take apart, because for the way I actually work, the other five mostly dissolve.
Here is the reconciliation, and it is the whole point of this piece. Redux treats every HTML output as a thing that must be git-diffed. Thariq treats every output as a thing that is only ever read. Both are wrong in the same way: they assume one output has one mode of review. In practice there are two kinds of thing, and you review them differently.
The first kind is a document: a report, a plan, a matrix, the safety binder. Its audience is a human, and the unit of review is the rendered artifact, read with careful eyes. You do not git-diff a document any more than you git-diff a PDF; you open it and read it and sign off. This is, word for word, the kind of review Redux himself says doc review actually is: "careful eyes for non-code docs," not diffing. He had the answer in his own essay and used it to argue the other way.
The second kind is a source of record: the code, the config, the CLAUDE.md, the data the report is built from. That lives in version control as text, and you review it by reading the diff, line by line. The HTML is never this. The HTML is a view, generated from reviewed inputs and thrown away and regenerated at will.
| The document | The source of record | |
|---|---|---|
| Audience | a humanauditor, supervisor, you next quarter | you + the agentwhoever edits the truth |
| Unit of review | the rendered artifactread it; don't diff it | the line diffread it line by line |
| Lives in | a static hostregenerable, disposable | gitdurable, authoritative |
| Format | HTMLa view of the inputs | markdown / plain textthe inputs themselves |
There is exactly one place where these two ledgers touch and it gets genuinely interesting: the annotated diff, where a review is read rendered but generated from a diff that lives in git. That deserves its own piece, and it has one. see "Annotated PR review, in one file"
The dek promised you a carve-out, and here it is, because defaulting HTML to everything reproduces the §02 failure in the opposite direction, format fighting content, just with the format winning and the content drowning. "Yes, that import is unused, remove line 14" does not want a stylesheet. Wrapping a one-line answer in 200 lines of boilerplate is the same insult to the reader as a compliance matrix crammed into ASCII; it is just dressed better.
So the carve-out is plain text: markdown, a chat message, whatever, for anything that is done being read the moment it is read. Conversational turns. Short answers. The quick yes/no. The thing you will never open twice. These are turns in a conversation, not artifacts, and a turn does not need a typeface.
The artifact gets HTML when it clears a low bar: it will be opened more than once, or by more than one person, or kept. Open twice, share once, or file it: that is when the format earns its weight. Below that bar, hand me the three sentences.
That is the whole rule, and it dissolves the fight Thariq and Redux were actually having. If a thing will be read rendered, shared, or kept, make it HTML. If it is a turn in a conversation, or the source of truth in a repository, make it text. Review your documents by reading them. Review your sources by diffing them. Never let a styled file become the thing of record.
Thariq gave us the canvas, and he was right that it is unreasonably good. Redux reminded us that a canvas you cannot review is a poster, not a document, and on review, the one place it counts, he was right too. The reconciliation was never about choosing a format. It was about knowing which of the two things you are making before you ask for it.
So: stop handing me the markdown your agent had to fight. And stop handing me the HTML it had no reason to build. Hand me the artifact, rendered, when there is an artifact, and three plain sentences when there are three sentences. That is not a compromise between two essays. It is the thing both of them were circling.