Thariq Shihipar, engineering lead for the Claude Code team, recently published a blog post (Using Claude Code: The Unreasonable Effectiveness of HTML) arguing that HTML, with its richer visualizations, color, and interactivity, improves the productivity of human-agent communication in many settings, especially when compared to default Markdown outputs. Goal communication, specification refinement, and output review are emerging bottlenecks in agentic workflows.
Shihipar described a common pain point among developers: As agents have become more and more powerful, I’ve found that Markdown has become an increasingly restrictive format. Specifically, I find it difficult to read a Markdown file of more than a hundred lines
[…] I also am increasingly not editing these files myself, but using them as specs and reference files.
I’ve started preferring HTML as an output format instead of Markdown and increasingly see this pattern being applied by others on the Claude Code team.
The Pro-HTML thesis is based on the observation that, as agents are increasingly used in complex and longer workflows, their outputs also grow in complexity and length, creating a cognitive bottleneck for humans. Proponents argue that, faced with this challenge, developers might give in to the temptation of simply accepting the output without review, possibly creating quality, maintenance, and security issues down the road.
According to this view, in workflows where human input is essential and cannot be automated away (e.g., goal and path setting, requirement exploration and refinement, guided remediation), or where human validation and verification are mandatory, an agent’s output format should allow for the quick capture of both the essence and details of the provided information and support the goal set by the user.
Shihipar prefers single-file HTML artifacts over Markdown to create visual, interactive workspaces that are customized to the goal at hand. Namely, Shihipar believes that specs, planning, and exploration; code review and understanding; interface design and prototyping; data exploration, analysis, and visualization; and generally any problem that would benefit from a tailored user interface could all benefit from HTML.
In a companion article to the blog post, Shihipar provides an example of custom throw-away HTML output requested to speed up the goal of triaging tickets:
This other example seeks to speed up the PR review process. The HTML output is poised to be easier to scan than scrolling through a terminal:
Shihipar’s thesis sparked widespread discussion on Hacker News, Reddit, and Medium, dividing developers into those who embraced HTML’s visual density and those who warned against abandoning Markdown’s plain-text simplicity.
Responding to Shihipar’s initial framework, Simon Willison observed that with current context window sizes and faster, cheaper models, defaulting to Markdown outputs may no longer be the best strategy:
I’ve been defaulting to asking for most things in Markdown since the GPT-4 days, when the 8,192 token limit meant that Markdown’s token-efficiency over HTML was extremely worthwhile.
Thariq’s piece here has caused me to reconsider that, especially for output. Asking Claude for an explanation in HTML means it can drop in SVG diagrams, interactive widgets, in-page navigation and all sorts of other neat ways of making the information more pleasant to navigate.
Others believe that substituting Markdown for HTML is a step backward, even in the aforementioned use cases. They emphasize a loss of source readability, the security and infrastructure risks of possibly unsafe HTML, the token tax of HTML vs. Markdown, and suboptimal git integration (e.g., around diffs).
Some developers nonetheless are creating custom tools (e.g., html-artifacts, an open-source Claude Skill by Greg Dogum with a recognition heuristic that switches to HTML outputs based on the task at hand).
In the end, Shihipar’s thesis may possibly be a case of using the right tool for the job: All of the above is to say that the real reason I use HTML instead of Markdown is that it helps me feel much more in the loop with Claude. As Claude takes on more, I’d noticed I was reading plans less closely, and I wanted a way to stay engaged with its choices rather than just hand them off. HTML turned out to be exactly that.
AI agent platforms are actively seeking improvements in human-agent interfaces, including by adding more interactive interfaces to the standard text-based mechanism. In particular, Generative UI allows agents to create UIs on the fly that are customized to a human request.