Stop letting your agents write Markdown

In May I wrote that asking your coding agent for an HTML page instead of Markdown was pretty, expensive and disposable. I put a number on the expense, 3 to 5 times the tokens, and I had not measured it. I also said HTML would wreck your diffs, and I had not tested that either.

Four months later the idea has not gone away. It shipped. So I went back and measured what I had only asserted.

What changed since May ​

Thariq Shihipar's essay on the Claude Code team's use of HTML was republished on the Claude blog on 20 May, a week after my post, and it is more careful than the X version I reacted to. He concedes the cost himself: "While Markdown often uses fewer tokens, I've found that the added expressiveness of HTML and the much higher likelihood of me actually reading it means I get overall better output." His argument is that a document you actually read is worth more than one you skim, and that is worth paying for.

Then on 18 June Anthropic shipped artifacts in Claude Code. The agent writes a self-contained page and publishes it to a private URL. Every publish is a new version, people in your organisation can comment on it, and a page can call your MCP connectors when someone opens it. The documentation says, without a figure, that "a styled page is more token-intensive than the same content as terminal text."

Google's Antigravity followed on 26 August with agents that produce "interactive HTML/CSS/JS components". Cursor had canvases since April.

That retires my "throwaway pages" argument. A page with a version history, a comment thread and a stable URL is not throwaway. What is left is the cost, and nobody had published a number for it. Cloudflare's often-quoted 80% saving measures pages an agent reads. I wanted the cost of the pages it writes.

The measurement ​

Two tasks, each in both formats, three runs per cell, on Claude Code 2.1.273 with Opus 5. No tools, no project settings, no MCP servers, one turn. The only difference between the formats is the last line of the prompt.

Task A: Write an implementation plan for adding per-user rate limiting to an
Express.js REST API with five endpoints: auth, users, orders, payments and
webhooks. Include the steps, the risks, and a rollout checklist.

Task B: Review this diff as a senior engineer and write the code review summary
for the author: what is wrong, how severe, and what to change.
[a fixed 30-line TypeScript diff: a coupon path with an empty catch, a mail
call after the insert, and a refund without a guard]

Markdown: Return the document as Markdown.
HTML:     Return the document as a single self-contained HTML file.

claude -p "$PROMPT" --model claude-opus-5 --tools "" --setting-sources "" \
  --strict-mcp-config --no-session-persistence --output-format json

Output tokens, cost and duration come from the JSON that claude -p returns. Cost is list price. "Visible words" is the word count after stripping tags, styles and scripts, a rough check that both formats said the same amount.

HTML took 1.9 times the output tokens for the plan and 2.2 times for the review. The visible content was about the same size. Each page carried roughly 2,400 characters of CSS before it said anything.

So the cost is real and it is about double. My 3 to 5 times was an exaggeration. On a single document the difference is fifteen cents and forty seconds. You notice the forty seconds first, and both compound in a loop that regenerates the page on every pass.

One run is left out of the table. A single HTML plan came back with tools available despite --tools "", spent 65,250 tokens and $2.13 on a loop of empty shell calls, and never produced the page. I could not reproduce it, and a session with the wrong tools says nothing about the format, so I re-ran it. It is also a reminder that averages over three runs hide what one bad run costs.

The diff that did not explode ​

I claimed HTML diffs would be unreadable. To test it I took the first document of each cell and asked for a narrow revision, with the whole document back in the same format. I counted the diff on the document alone, leaving out the note about its changes that the model added after the HTML. For the plan: add a risk about Redis being unavailable, start the rollout at 5% of traffic. For the review: downgrade the email finding by one severity level, add a sentence on refund idempotency.

Both are reviewable. The HTML plan diff was even the smaller one. The larger HTML review diff comes from the model moving the whole finding card from the Major section to the Minor section, which is the correct edit and reads fine in a pull request. When the model edits in place, the two formats produce diffs of about the same size. My claim does not survive this test.

What the test does not cover is the case I was actually worried about: regenerating a page from scratch instead of revising it. Then every line can change, and that holds for Markdown just as much. So have the documents you keep revised instead of regenerated.

Where Markdown still wins: what agents read ​

The stronger case for Markdown in 2026 is on the other side of the conversation.

Mintlify ran Claude Code and Codex against 20 documentation sites, 2,400 runs, and published it on 17 July. Agents hit on average 2.23 dead links per task on HTML docs, 1.42 on Markdown, and 0.11 on Markdown with an llms.txt index. Cloudflare serves Markdown to any client that sends Accept: text/markdown, and measured one of its own pages at 16,180 tokens as HTML and 3,150 as Markdown. llms.txt v2, from 10 August, now recommends advertising the Markdown version of a page with a rel="alternate" link.

That is where a format choice moves real numbers. A plan a human reads once costs twice as much as HTML. Cloudflare's page was five times larger as HTML than as Markdown, and an agent reads documentation again on every task. In Mintlify's runs it also got lost more often on HTML.

When the page earns its price ​

After measuring, my rule is narrower than the one I published in May.

• Ask for HTML when a human has to see structure to make a decision. A migration plan with dependencies, a review with a dozen findings sorted by severity, a comparison someone has to sign off on. Thariq's point holds here: a page that gets read beats a Markdown file that gets skimmed, and doubling the cost of a sixteen-cent document is cheap.
• Keep Markdown for anything an agent reads back. Specs, CLAUDE.md, docs, the plan the next session starts from. The cost there is paid on every read, in tokens and in wrong turns. And read that spec yourself, whatever format it arrives in.
• Keep Markdown inside loops. A page regenerated on every iteration pays the double cost every time and makes you wait for it.
• Revise pages you keep, never regenerate them. That is what keeps the diff small, in either format.

The title of this post still works as a provocation, just not as advice. Let your agents write HTML when the reader is a person who has to decide something. Make them write Markdown when the reader is another agent.