> Thariq from Anthropic's Claude Code team wrote an internal blog post titled "The Unreasonable Effectiveness of HTML" — a direct homage to Rich Sutton's classic paper. His core claim is simple: as agents evolve from "helping you write code" to "helping you deliver entire projects," Markdown — a format nobody reads past 100 lines — can no longer keep up.
---
1. The Twilight of Markdown: 100 Lines as a Cognitive Ceiling
Thariq's original words are blunt:
> "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 isn't personal preference — it's an organizational hard constraint. As Claude Code handles increasingly complex work (writing specs, drawing architecture diagrams, building prototypes, reviewing code), Markdown's expressiveness falls short.
More fatally, Markdown's "editability" advantage is evaporating. As Thariq says:
> "When I do make edits, I'm usually prompting Claude to edit them, which removes one of markdown's largest benefits."
If editing itself happens via prompting an agent, Markdown's selling point of "easy for humans to edit" fails. What you need isn't a format humans can easily edit — it's a format where the agent can express rich information and humans actually want to read it.
---
2. HTML's Six Winning Cards
1. Information Density: Nearly Unlimited
Everything Markdown can do, HTML can do — but most of what HTML can do, Markdown cannot:
| Information Type | Markdown | HTML |
|---------|---------|------|
| Document structure | headers, bold, lists | + tabs, collapsible sections |
| Tabular data | simple tables | complex tables + sorting + filtering |
| Design data | ❌ | CSS styling system |
| Illustrations | ASCII art | SVG vector graphics |
| Code snippets | code blocks | + syntax highlighting + interactive execution |
| Interactive controls | ❌ | slider, knob, button |
| Workflow diagrams | ASCII arrows | SVG flowcharts |
| Spatial data | ❌ | absolute positioning, canvas |
| Images | ❌ | <img> tags |
Thariq gives a telling detail: in Markdown, Claude can only "approximate" colors with Unicode blocks like 🟥🟩🟦, whereas HTML lets it write CSS background-color directly.
2. Visual Clarity: Documents People Actually Read
HTML enables:
- Organizing sections with tabs
- Sidebar navigation
- Color-coded severity (critical/warning/info in code reviews)
- Mobile responsiveness
- Design prototypes: sliders adjust animation parameters with live previews
- Algorithm tuning: knobs change values, charts update in real time
- Configuration editing: edit, click "copy as JSON," paste back into Claude Code
- Prioritization: 30 Linear tickets as draggable cards in Now/Next/Later/Cut columns, with "copy as markdown" export
- Feature flag editing: form-based editor showing dependencies, warning when prerequisites are off
- Prompt tuning: editable prompt on the left, three sample inputs rendering live on the right, with a token counter
- Original post: https://www.anthropic.com/engineering/claude-code-html
- Example gallery: https://thariqs.github.io/html-effectiveness (20 HTML files)
- Author: Thariq (Claude Code team, Anthropic)
- Inspiration: Rich Sutton's "The Bitter Lesson" → this post's title "The Unreasonable Effectiveness of HTML"
- Context window: Claude Opus 4.7 supports 1M tokens
- Key data: HTML generation time 2-4x Markdown, the 100-line Markdown cognitive ceiling, 20 practical examples
- Core claim: Markdown suits short text editing; HTML suits complex information expression and bidirectional interaction
These aren't nice-to-haves — without them, nobody reads the document at all.
3. Easy Sharing: One Link
Markdown files are hard to share: browsers don't natively render them, emailing means attachments, and colleagues probably won't open them. HTML uploaded to S3 (or any static host) yields a single frictionless link.
4. Bidirectional Interaction: Documents Aren't Static
Thariq's examples:
This breaks the linear loop of "agent output → human reads → human feeds back → agent outputs again" and becomes humans operating directly inside the document.
5. Data Ingestion: Claude Code's Context Advantage
Why use Claude Code for HTML rather than Claude.ai or Claude Design? Because Claude Code can read your codebase.
While writing this post, Thariq had Claude Code read his code folder, find all generated HTML files, categorize them, and draw SVG illustrations of each type — which appear in the final article. Claude Code can also read MCP sources (Slack, Linear), the browser (Claude in Chrome), and git history — a context depth pure chat interfaces can't match.
6. Fun: Greater Human Investment
> "Making HTML documents with Claude is just more fun and makes me feel more involved and invested in the creation, and that by itself is enough."
This isn't just sentiment. When humans feel more ownership over output, they review, give feedback, and iterate more — accelerating the entire agent workflow loop.
---
3. Five Practical Scenarios
Scenario 1: Spec & Planning
Instead of a Markdown list of options, build an HTML grid showing six design directions side by side, each with annotated tradeoffs. Thariq's approach: "make a webpage" rather than "write a document" — brainstorming, mockups, and implementation plans all become HTML files, then get bundled as context for implementation sessions.
Scenario 2: Code Review
Instead of the GitHub diff view, an HTML file with inline margin annotations and severity-based color coding. Thariq says: "I attach a HTML code explainer to every PR I make now." It beats GitHub's default diff by focusing on specific logic (e.g., unfamiliar streaming/backpressure code), adding flowcharts, and marking risk levels.
Scenario 3: Design & Prototypes
Claude Design itself is HTML-based. Sketch design systems in HTML (tokens → swatches, components → contact sheets), then have Claude translate into React, Swift, or any target platform. Thariq's example: an animated checkout button prototype with a parameter-adjusting slider and one-click value copy.
Scenario 4: Reports & Research
Claude Code can synthesize across sources (Slack, codebase, git history, the web) into HTML reports: long documents with collapsible sections, interactive explainers, or slide decks (a few <section> tags plus 20 lines of JS).
Scenario 5: Custom Editing Interfaces
The most imaginative scenario: when describing things in text is painful, have the agent build a one-off HTML editor:
Core pattern: agent builds UI → human operates in the UI → clicks export → pastes result back to the agent. The human stays in the loop, but the loop gets tighter.
---
4. FAQ
Q1: Isn't token efficiency worse?
Markdown does use fewer tokens. But Thariq responds:
> "With the 1MM context window in Opus 4.7, the increased token usage is not really noticeable."
With 1M-token context windows, HTML's extra tokens are negligible. More importantly: the gain in expressiveness — leading to documents people actually read — far outweighs the token cost.
Q2: When do you still use Markdown?
Thariq: "I have honestly stopped using markdown altogether for almost everything." He calls himself an "HTML maximalist."
Q3: Doesn't generation take longer?
Yes, 2-4x. But Thariq believes the result is worth it. The implicit logic: if humans don't read the agent's output, generating it faster is worth zero. HTML is slower, but far more likely to be read.
Q4: What about version control?
Thariq admits:
> "This is honestly one of the biggest downsides of HTML, HTML diffs are noisy and hard to review compared to Markdown."
This is the biggest weakness of the HTML approach, with no good solution yet — just acceptance.
Q5: How do you keep Claude's design taste from being ugly?
Two methods: 1. Use Anthropic's frontend design plugin 2. Create a design system HTML file (having Claude extract styles from your codebase) that all future HTML files reference
---
5. Twenty Examples: From Exploration to Custom Editors
Thariq built a showcase page (https://thariqs.github.io/html-effectiveness) with 20 self-contained .html files, grouped by category:
| Category | Count | Description | |------|------|------| | Exploration & Planning | 3 | Side-by-side option comparison, drill-down on a choice | | Code Review | 3 | Annotated diff, call graph, module diagrams | | Design | 2 | Design system artifact, component contact sheet | | Prototyping | 2 | Animation tuning, interactive prototype | | Illustrations & Diagrams | 2 | SVG flowcharts, technical illustrations | | Decks | 1 | HTML slides with arrow-key navigation | | Research & Learning | 2 | Collapsible explainer, tabbed code sample | | Reports | 2 | Status update, post-mortem | | Custom Editors | 3 | Drag-to-sort, form editor, prompt tuning interface |
Each file turns "a document you'd skim" into "something you'd actually read."
---
6. One-Sentence Takeaway
Thariq's post isn't a technical proposal — it's a paradigm statement: when agent output shifts from "text humans will edit" to "information carriers humans will read," the logic of format choice changes completely. Markdown's brevity is an advantage under 100 lines and a bottleneck beyond them. HTML's "heaviness" isn't a burden — it's the necessary cost of carrying complex information.
And the core insight comes in the final line:
> "I feel much more in the loop with Claude... instead of leaving Claude to make its choices."
HTML doesn't make the agent more autonomous — it makes the human more present.
---
References
*A counterintuitive takeaway: in the agent era, human-machine communication formats aren't simplifying — they're complexifying. Markdown is a Web 1.0 artifact that assumes humans will read, edit, and maintain text. The truth of the agent era is that humans can't get through 100+ lines of plain text, and editing is delegated to agents. Formats need to carry not "editability" but "information density" and "interactivity." HTML wins not because it's simpler, but precisely because it's complex enough to carry everything an agent wants to express.*