Skip to content

category: concept updated: 2026-05-10 status: draft tags: [agent-output, html, markdown, claude-code] sources: title: "Agent Output Formats" [thariq-html-effectiveness.md] confidence: medium

title: ""

Summary

The file format that agents produce as their primary output has a disproportionate effect on the usability, richness, and shareability of their work. As of 2025–2026, the dominant pattern is Markdown — but a growing case exists for HTML as the better default for complex deliverables.

Overview

LLM agents need to produce structured output. The format choice affects:

  1. How easily humans can read and evaluate it
  2. How richly information can be represented without rendering tools
  3. Whether the output can stand alone as a shareable artifact
  4. Whether it can be iterated on by the agent in subsequent steps

Markdown became the default because early agents produced short texts (summaries, outlines, code snippets) where its benefits (plain text, easy to diff, human-editable) dominated. As agents produce longer, more complex work — specs, plans, reports, diagrams, interactive prototypes — the format limits become visible.

Markdown as Agent Format

Markdown is the dominant agent output format as of 2025–2026.

Strengths: - Plain text — works with git, diffs, review tools natively - Human-editable without tools - Portable across editors and platforms - Adequate for simple structures: headings, lists, code blocks, basic tables - Small file size, fast to parse

Limitations for complex work: - Beyond ~100 lines, readability degrades for non-technical readers - No native support for color, rich diagrams, or interactive elements - ASCII/emoji diagrams are a hack with limited expressiveness - Tables break with complex content (URLs with pipes, long text) - Layout is rigid — one column, linear flow - When agents edit markdown files (rather than humans reading them), the "human-editable" benefit no longer applies

HTML as Agent Format

HTML as agent output was popularized by Thariq at Anthropic in May 2025. (thariq)

Strengths: - Rich visual representation: color, diagrams, interactive charts - Interactive elements: clickable flows, live editors, slide decks - Layout flexibility: side-by-side comparisons, tabs, accordions - Self-contained: one file, renders in any browser - No build step or tooling required - Agent generates directly, human reads directly — no intermediate transformation

Limitations: - Not plain text — diffs are ugly, git integration is poor (HTML is not version-control-friendly in the same way) - Cannot be read by non-browser tools (grep, search, indexing) - Requires a browser to view (though virtually any device has one) - Harder to review changes (diffs of HTML are nearly unreadable) - Security concerns if agents generate HTML from untrusted input

When HTML wins (per Thariq's 19 demos): - Code review artifacts (annotated diffs, module maps) - Design systems (color swatches, component variants) - Prototypes (clickable flows, animation sandboxes) - Diagrams (SVG figures, annotated flowcharts) - Slide decks (arrow-key navigable presentations) - Research explainers (live interactive models, tabbed content) - Status/incident reports (timelines, charts, checklists) - Custom editing interfaces (drag boards, feature flag editors, prompt tuners)

When Markdown still wins: - Code (agents are writing code, which is a form of structured text) - Simple specs and requirements - Git-integrated diffs and code review - Short-form notes and outlines - Any context where the agent (not a human) is the primary reader/consumer

Key Cases

Case 1: Claude Code output is reviewed by humans via browser → HTML is superior for anything beyond simple text. Interactive visualizations, color-coded severity, click-through debugging paths convey information that markdown simply cannot.

Case 2: Claude Code output is reviewed by humans via git → Markdown wins. Diffs of HTML are nearly unreadable; you need the rendered version.

Case 3: Claude Code output is consumed by another agent → Markdown or JSON wins. Agents process structured text much better than rendered HTML.

Sources