Using Claude Code: The Unreasonable Effectiveness of HTML

Author: Thariq Shihipar — @trq212
Role: Engineering Lead, Claude Code team at Anthropic
Published: May 8, 2026
Source: Twitter/X thread
Viral reach: 10.4M views · 14K likes · 1.8K retweets · 28.7K bookmarks

Source

This article originated as a long-form post on Twitter/X by thariq-shihipar, who leads the Claude Code engineering team at Anthropic. It sparked widespread discussion among AI researchers, developers, and agent practitioners. A companion site (thariqs.github.io/html-effectiveness/) collects 20 self-contained HTML examples demonstrating the argument in practice.

The Core Argument

Markdown became the dominant format for AI outputs because it is simple, portable, supports rich text, and is easy to edit. For years, this was the right default — especially when token limits were tight.

Thariq's claim: this is now the wrong default.

The argument is not about a hidden command or a new model trick. It is simpler: ask Claude Code to output HTML instead of Markdown.

That single change shifts the shape of the work. Many people still ask coding agents for Markdown, then manually read, sort, annotate, and reshape the result. HTML gets closer to the actual workspace — it is a document you can review, interact with, and act on, not just read.

The Key Insight: HTML Is an Interface, Not a Document

Markdown is great for notes. It is weak when the work becomes dense.

Plans, code reviews, research summaries, and issue triage quickly need:
- Hierarchy and visual emphasis
- Filtering and status tracking
- Interactive elements (collapsible sections, tabs, hover states)
- Color-coded severity or progress indicators
- Inline diagrams and visual callouts

HTML gives you all of that in one self-contained local file. Cards, tables, progress bars, buttons, and filters can turn a model response into something closer to a working interface — without shipping to production.

Markdown feels like an endpoint. HTML feels like a starting point.

HTML as a Temporary Workspace

The biggest shift Thariq describes is treating Claude Code not only as a code generator, but as a producer of temporary dashboards, review pages, planning boards, and lightweight editors.

Examples from the HTML effectiveness collection:

  • Code review: An HTML page showing each issue as a card with severity, file path, impact, suggested fix, and testing notes — with top navigation for filtering by severity
  • PR descriptions: Color-coded diffs with inline margin annotations, severity highlighted visually not just textually
  • Exploration: Multiple options laid out side by side as cards you can compare at a glance rather than reading sequentially
  • Research explainers: Collapsible sections, tabbed code samples, a glossary in the margin
  • Prototype demonstrations: Real easing curves and click-through interactions you can feel, not read about

None of these need to ship. They only need to reduce the cost of understanding and acting on the result.

Why HTML Works Better Than Markdown for Handoff

The hard part of agentic work is not only execution. It is handoff.

A model may finish a task, but a human still has to judge risks, split follow-ups, share context, record decisions, and decide what happens next. If that handoff remains a long Markdown block, it becomes another pile of text to manage.

HTML works as a bridge. It is lighter than building a full app, but richer than static notes. It lets the agent leave behind something immediately usable — not just something readable.

A Practical Prompt Template

Do not only output Markdown. Generate a single-file HTML report with an executive summary, risk levels, collapsible details, action items, and next-step recommendations. Keep all styles inline so I can open it locally.

For code review specifically:

Output the review as an HTML page. Show each issue as a card with severity, file path, impact, suggested fix, and testing notes. Add top navigation for filtering by severity.

The Tradeoffs

HTML is heavier than Markdown. It can create unnecessary styling. It needs a browser to preview. It can overcomplicate simple tasks.

The practical heuristic: ask for HTML when the output needs repeated reading, team review, status tracking, comparison, filtering, or follow-up editing. For quick disposable notes, Markdown is still faster.

Companion Examples

Twenty self-contained HTML files are collected at thariqs.github.io/html-effectiveness/, grouped by use case:

  • Exploration & Planning (3 demos)
  • Code Review (3 demos)
  • Design (2 demos)
  • Prototyping (2 demos)
  • Illustrations & Diagrams (2 demos)
  • Decks (1 demo)
  • Research (2 demos)
  • Reports (2 demos)
  • Custom Editors (3 demos)

Each one demonstrates a case where HTML replaced a wall of Markdown with something you'd actually interact with.

Why This Matters for Agentic Engineering

The deeper lesson: don't only optimize prompts. Optimize the artifact the agent gives back.

When the output format shifts from text to interface, the same information becomes faster to parse, easier to act on, and more likely to actually get used after the model stops talking.

The distinction is simple: Markdown is a report. HTML is an interface. Reports are for reading. Interfaces are for continuing the work.

Relevance to dark-factory-kb

This aligns with the output quality concerns raised in simon-w-agentic-engineering-patterns — the shift from text-only output to richer artifacts. It also connects to kelly-factory-overview QA gates: replacing Markdown PR reviews with HTML artifacts would reduce operator cognitive load and increase the speed and quality of gate decisions.

See simon-willison-unreasonable-effectiveness-html for simon-willison's complementary perspective, which extends Thariq's argument and provides additional practical context.

  • world-model — HTML artifacts as temporary workspaces for agents: richer handoff documents that reduce cognitive load on the human reviewing agent output

  • sharpener — the shift from Markdown reports to HTML interfaces is a sharpening of the output artifact: not just readable, but actionable and interactive

  • Thariq Shihipar, "Using Claude Code: The Unreasonable Effectiveness of HTML", Twitter/X, 2026-05-08 — https://x.com/trq212/status/2052809885763747935

  • HTML effectiveness examples collection: https://thariqs.github.io/html-effectiveness/
  • simon-willison, "The Unreasonable Effectiveness of HTML", simonwillison.net, 2026-05-08 — https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/