Thariq, an engineer on Anthropic's Claude Code team, wrote an internal blog post titled "The Unreasonable Effectiveness of HTML" (echoing Rich Sutton's classic "The Bitter Lesson"). His core claim: as agents evolve from "helping you write code" to "delivering complete projects," Markdown—a format nobody reads past 100 lines—can no longer keep up.
Why Markdown Falls Short
> "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."
This is an organizational constraint, not a personal preference. Worse, Markdown's editability advantage is disappearing:
> "When I do make edits, I'm usually prompting Claude to edit them, which removes one of markdown's largest benefits."
If editing happens via prompts, you need a format that lets the agent express rich information and that humans are willing to read—not one that is merely easy for humans to edit.
Six Advantages of HTML
1. Information density — Markdown can't do styled tables, CSS design systems, SVG diagrams, interactive controls (sliders, knobs, buttons), absolute positioning, or embedded images. Even colors in Markdown are approximated with emoji blocks like 🟥🟩🟦; HTML just uses background-color.
2. Visual clarity — tabs, sidebar navigation, severity color-coding, mobile responsiveness. These are what make documents actually get read.
3. Easy sharing — upload to S3 or any static host; one link, zero friction, unlike Markdown files browsers won't render.
4. Two-way interaction — design prototypes with parameter sliders, algorithm tuning with live-updating charts, config editors with "copy as JSON" back into Claude Code. The linear loop (agent output → human reads → human replies) becomes direct manipulation inside the document.
5. Data ingestion — Claude Code can read your codebase, MCP sources (Slack, Linear), the browser, and git history, then synthesize rich HTML output.
6. Engagement — "Making HTML documents with Claude is just more fun and makes me feel more involved and invested in the creation."
Five Practical Use Cases
- Spec & Planning: instead of Markdown checklists, an HTML grid comparing six design options side by side with tradeoffs; these files become context for the implementation session.
- Code Review: HTML files with inline margin annotations, severity color-coding, and flowcharts. Per Thariq: "I attach a HTML code explainer to every PR I make now."
- Design & Prototypes: design systems as HTML (tokens, component contact sheets) that Claude translates to React/Swift; e.g., a checkout-button animation prototype with tuning sliders.
- Reports & Research: HTML reports synthesized across Slack, codebase, git history, and the web—collapsible sections, interactive explainers, or slide decks (a few
<section>tags plus ~20 lines of JS). - Custom Editing Interfaces: the most creative case—when describing things in text is painful, have the agent build a disposable HTML editor: drag-and-drop ticket prioritization (Now/Next/Later/Cut), feature-flag forms with dependency warnings, prompt-tuning panels with live sample rendering and token counters. The pattern: Agent builds UI → human operates in the UI → export results back to the Agent.
- Token efficiency? Markdown is cheaper, but "with the 1MM context window in Opus 4.7, the increased token usage is not really noticeable." Readability gains outweigh token cost.
- When is Markdown still used? "I have honestly stopped using markdown altogether for almost everything." He calls himself an "HTML maximalist."
- Generation time? 2–4x slower, but worth it—an unread output has zero value regardless of speed.
- Version control? The biggest weakness: "HTML diffs are noisy and hard to review compared to Markdown." No good solution yet; it must be accepted.
- Ugly design? Use Anthropic's frontend design plugin, or maintain a design-system HTML file extracted from your codebase that all outputs reference.
- Original post: https://www.anthropic.com/engineering/claude-code-html
- Examples: https://thariqs.github.io/html-effectiveness
- Author: Thariq (Claude Code team, Anthropic); title inspired by Rich Sutton's "The Bitter Lesson"
- Key data: HTML generation is 2–4x slower; ~100-line Markdown readability ceiling; Claude Opus 4.7 supports a 1M-token context window
FAQ Highlights
20 Working Examples
Thariq published a showcase at https://thariqs.github.io/html-effectiveness with 20 self-contained .html files grouped by category: Exploration & Planning (3), Code Review (3), Design (2), Prototyping (2), Illustrations & Diagrams (2), Decks (1), Research & Learning (2), Reports (2), and Custom Editors (3).
The Takeaway
This is less a technical proposal than a paradigm statement: when agent output shifts from "text humans edit" to "information carriers humans read," format selection logic changes entirely. Markdown's simplicity is an advantage under 100 lines and a bottleneck beyond. HTML's weight isn't a burden—it's the necessary cost of carrying complex information.
> "I feel much more in the loop with Claude... instead of leaving Claude to make its choices."
Counterintuitively, HTML didn't make the agent more autonomous—it made the human more present.