Thariq Shehzad, on the Claude Code team at Anthropic, has switched from markdown to HTML as his default agent output format. The reasoning is more honest than a format-war argument would suggest, because it’s about what humans will actually read. He opens by acknowledging what markdown was for:
Markdown has become the dominant file format used by agents to communicate with us. It’s simple, portable, has some rich text capability and is easy for you to edit. Claude has even gotten surprisingly good at using ASCII to make diagrams inside of markdown files. But as agents have become more and more powerful, I have felt that markdown has become a restricting format.
Then the pivot:
As Claude is able to do more complex work, it is also writing larger and larger specs and plans. In practice, I’ve found I tend to not actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it. But HTML documents are much easier to read, Claude can organize the structure visually to be ideal to navigate with tabs, illustrations, links, etc.
When the spec gets long enough that you stop reading it, you’ve quietly moved from review to rubber-stamp. Shehzad’s answer isn’t to ask Claude for shorter specs. It’s to make the artifact something a human will actually open, scroll, and share. A controllable, shareable artifact is most of what made personal computing legible in the first place; HTML is the format that already does it.
He puts the trade-off honestly when the obvious objection comes up:
While markdown often uses fewer tokens, I’ve found that the added expressiveness of HTML and the much higher likelihood of me reading it means I get overall better output. With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable in the context window.
And the close is the real argument:
The real reason I use HTML is that I feel much more in the loop with Claude. I had begun to fear that because I had stopped reading plans in depth I would simply have to leave Claude to make its choices. But I am happy to say instead that I feel more in the loop than ever before when using HTML.

Using Claude Code: The Unreasonable Effectiveness of HTML
Thariq Shehzad on Anthropic’s Claude Code team switched his agent output from markdown to HTML — because what keeps Claude honest is what humans actually read.



















