There's a new trend sweeping through the AI developer community, and for once, I actually get the appeal. Instead of asking your coding agent to spit out yet another wall of Markdown, you ask it to generate an HTML file instead. Open it in a browser. And suddenly, your agent's output goes from a flat document to a rich, interactive, beautiful page.
Karpathy is doing it. The Claude Code team is writing about it. Theo made a whole video about it. And honestly? The results look stunning.
But as someone who has spent the better part of this series pointing out the gap between what AI demos show and what AI production delivers, I can't just nod along. So let's do what we always do here: dig past the excitement and ask the uncomfortable questions.
The case for HTML (it's real)
Let me be clear: the argument for HTML over Markdown is legitimate. Thariq Shihipar from the Claude Code team laid it out well: when you're asking an agent to generate a spec document, a project roadmap, or a code review summary, Markdown gives you headers and bullet points. HTML gives you a canvas.
Think about what that means in practice:
- Information density. A single HTML page can contain collapsible sections, color-coded status indicators, sortable tables, and inline SVGs. The same information in Markdown would be a 500-line wall of text that nobody reads past the third heading.
- Visual hierarchy. CSS lets you encode priority through size, color and position. In Markdown, everything looks equally important, which means nothing is.
- Interactivity. Imagine your agent generates a migration plan with an interactive dependency graph, or a performance report where you can filter by endpoint. Try doing that in a
.mdfile.
Karpathy himself endorsed the approach: just append "structure your response as HTML" to your query, open the file in a browser, and you get something that actually communicates. He's right. It works. I've tried it.
The part nobody is talking about
Now here's where my skepticism kicks in.
Token economics
An HTML page with Tailwind classes, embedded CSS and structural markup is easily 3-5x the token count of the equivalent Markdown. That collapsible sidebar with smooth animations? That's not free. Every <div class="flex items-center justify-between p-4 bg-gradient-to-r from-slate-800 to-slate-900"> is tokens you're paying for.
In an agentic loop where the model iterates on its own output, those tokens compound fast. Your beautiful, interactive spec document might cost $2 instead of $0.40. Multiply that across a team generating dozens of these per day, and your API budget starts looking like your cloud bill: a number that grows faster than anyone anticipated.
Version control is a nightmare
Markdown diffs are clean. You can review a .md file change in a pull request and immediately see what changed. HTML diffs? Good luck. A single change in content can cascade through dozens of lines of structural markup, class names, and wrapper divs. The signal-to-noise ratio in a diff goes from excellent to catastrophic.
If you're using these HTML outputs as documentation, as many advocates suggest, you're building a documentation system that is fundamentally hostile to version control. Every review becomes an exercise in parsing visual noise to find the actual content change.
The disposability problem
This is the one that bothers me most. The entire pitch for HTML agent output is that it's ephemeral. Generate it, look at it, maybe share a screenshot, move on. Thariq explicitly describes these as "throwaway pages."
But we already have a word for content that looks impressive, takes significant compute to generate, and has no lasting value: AI slop.
When every agent interaction produces a beautifully styled webpage that gets glanced at once and discarded, we haven't improved the communication between human and machine. We've just made the waste prettier. The underlying information could have been three bullet points, but instead it's wrapped in a gradient background with smooth animations, because the medium has become the message.
The real question: who is this for?
Here's the thing that the HTML enthusiasts haven't grappled with. There are two fundamentally different use cases being conflated:
1. Visualization of complex data. If your agent is analyzing a codebase and producing a dependency graph, an interactive HTML visualization is genuinely better than an ASCII art diagram. No argument there. This is the strong case.
2. Dressing up simple output. If your agent is answering a question, writing a summary, or generating a todo list, wrapping it in HTML adds nothing but cost and complexity. A Markdown file opened in any editor, preview pane, or documentation site does the job perfectly.
The problem is that the trend doesn't distinguish between these cases. The message isn't "use HTML when visual density matters." The message is "stop letting your agents write Markdown," full stop. And that absolutism is exactly the kind of thinking that leads to developers reaching for heavyweight solutions to lightweight problems.
The pattern we keep repeating
We've seen this before. Every few months, the AI developer community discovers a new thing that agents can do, mistakes capability for necessity, and rewrites their entire workflow around it.
Remember when the answer to everything was "just use a vector database"? When every problem needed RAG? When agentic loops were going to replace all linear code? Each of these tools has genuine value in specific contexts. But the hype cycle turns every useful tool into a universal hammer.
HTML output for agents is a useful tool. It will become the default in certain specific workflows: prototyping, data visualization, stakeholder presentations. And in those contexts, it's excellent.
But the breathless "Markdown is dead" narrative is, like most breathless AI narratives, a story that's more exciting than accurate.
What to actually do
If you want to use HTML output effectively, here's the pragmatic approach:
- Use it for visualization, not communication. If the output needs to be seen rather than read, HTML wins. For everything else, Markdown is fine.
- Watch your token spend. Track the cost difference. If you're paying 4x more for output that gets looked at once, you're optimizing for aesthetics over value.
- Don't check it in. HTML agent output belongs in
/tmp, not in your repository. The moment you version-control generated HTML, you've created a maintenance burden that will outlive the enthusiasm. - Keep the source of truth in plaintext. Your specs, docs and plans should live in formats that diff cleanly, render anywhere, and don't require a browser to read.
In closing
I like beautiful things. I genuinely enjoy opening an HTML file generated by Claude and seeing a polished, interactive page instead of yet another Markdown wall. There's a visceral satisfaction in it.
But satisfaction isn't strategy. The question isn't whether HTML output looks better than Markdown. It obviously does. The question is whether the cost, the disposability, and the version-control hostility are worth it for your specific use case.
For most developer workflows, most of the time, the answer is no. A well-structured Markdown file, written by an agent that knows what information actually matters, will always beat a beautifully styled webpage that says the same thing in five times the tokens.
The medium is not the message. The information is the message. Don't let a pretty wrapper distract you from asking whether there's actually anything inside.