Coding Agents: Enhanced Readability with HTML and Diagrams

Presenting the responses of a coding agent in HTML rather than in plain text allows for a clearer distinction between the essential and the superfluous. Diagrams generated by the agent, particularly with Archify, make it possible to map out pipelines such as OCR and classification. These practices apply almost systematically, except in simple cases.

Diagrams to Explain an End-to-End System

The creation of diagrams is a central lever to make exchanges with a coding agent more actionable. A GitHub package, Archify, produces highly visual schemas capable of aggregating a lot of information. These diagrams serve to understand the functioning of sections of an application, for example, the processing chain of a download. In this example, the visual representation may include a classification step, OCR, and other data extractions. This mapping facilitates the understanding of a document pipeline and the modifications to be made. The use of diagrams is recommended whenever a mechanism or information can be represented graphically, as the tool is rich in information. The approach is based on the idea that visual structuring is more intuitive for a human reader.

Moving from Plain Text to Structured HTML Output

The main recommendation is to ask agents to deliver their outputs in HTML rather than as text streams in the terminal. In practice, this approach applies to 90 to 95% of interactions, as the terminal provides a TXT equivalent without advanced formatting capabilities. Plain text may suffice for machine reading, but it makes selecting key elements more difficult for a human. In contrast, a rendering close to a markdown document, with headings and quotes, enhances attention and understanding. In HTML, the agent can structure the information with headers, bold for critical points, highlights, and visuals, including screenshots useful for application analysis. This structuring improves the overall effectiveness of communication.

Reorganizing Output to Avoid Scattered Information

A recurring problem is information scattered across multiple locations in a discussion thread. An intermediate step is to request a comprehensive summary at the end of the thread to consolidate the context. However, this consolidation is not enough if the presentation remains unformatted or contains irrelevant elements. The recommendation is therefore to couple this reorganization with structured formatting to limit re-readings and exposure to superfluous content.

When to Keep Inline Display and Reported Usage Intensity

Exceptions exist for very simple cases, where only a few quick pieces of information are sought: inline reading is then maintained. In practice, this presentation approach can be used up to 100 times a day and applied to nearly all coding sessions. These practices address the difficulties of reading terminal outputs, even in contexts with dedicated applications, and the unstructured nature of plain text. The bottom of threads is indeed re-read very frequently on a daily basis. The goal is to better align with agents such as Claude Code or Codex and clarify their intentions. Since the terminal does not natively offer advanced formatting, these methods are a way to improve the efficiency of exchanges. A quote block illustrates, by contrast, the value of formatting that breaks linearity.