More tools for visualizing code have been appearing recently.
This makes sense. Working with coding agents is becoming ordinary, and developers are still trying to find good ways to understand the code those agents produce.
There is no single established method yet. Some people use approaches such as spec-driven development. Others use dependency graphs, architecture maps, and diagrams instead of reading every generated file from beginning to end.
Several recent tools approach this from different directions:
- GitDiagram generates an interactive architecture diagram from a GitHub repository.
- CodeBoarding analyzes a codebase and produces layered architecture documentation.
- OpenHop lets an agent describe a particular code flow as an interactive walkthrough.
- diagram-design is a skill for producing more polished editorial diagrams.
- Archify helps agents create architecture, workflow, data-flow, sequence, and lifecycle diagrams.
- FlowPeek, which I built, previews Mermaid diagrams already visible on the screen.
These tools do not all solve the same problem. Some analyze an existing codebase. Some help an agent create a better diagram. Others make the result easier to view or share.
What they have in common is the idea that looking at the structure or flow can be useful before reading all the code.
Why Mermaid fits this workflow
Mermaid has been part of this for a while.
It is text, so an agent can generate and modify it easily. When the syntax is slightly wrong, a person can usually understand and correct it without much effort.
It also fits into Markdown and is supported by GitHub and many other tools. A diagram can live next to the code or documentation it describes without requiring a separate binary file.
I have been using Mermaid with language models for more than three years.
When ChatGPT first appeared, its output was too limited for me to delegate much of the design. I still designed larger systems myself, wrote detailed specifications, and used the model for relatively small parts of the implementation.
As the models improved, I gradually stopped asking only for code. I began asking them to explain the structure first, often as a Mermaid diagram.
With coding agents such as Codex and Claude Code, this has become part of my normal workflow.
My workflow
I usually begin with an unstructured list of requirements.
I write down what I want, often without organizing it very carefully, and ask the agent to explore the codebase and produce an implementation plan.
Once the plan looks reasonable, I ask it to draw the architecture before it starts writing code.
I do not always ask for the same kind of diagram.
For a change to an existing system, I usually ask for an as-is and to-be view. This makes it easier to see what will actually change instead of discussing the plan only as a list of tasks.
For a new program, I first ask for a broad architecture diagram. At this stage, I mostly want to check whether the agent’s interpretation matches the structure I have in mind.
After that, I may ask for a separate data-flow diagram. A component can appear to be in the right place while still receiving, transforming, or storing data in the wrong way. Looking at the data flow often reveals questions that are difficult to notice in a general architecture diagram.
Some components need another view. If a component has a complicated lifecycle, I ask for a state or sequence diagram that focuses only on that part.
By the time these diagrams look right, most of my larger questions have already been answered. Only then do I ask the agent to proceed with the implementation.
The diagram does not prove that the implementation will be correct. It gives me a cheaper place to find misunderstandings. Correcting a box or an arrow before implementation is usually easier than correcting the same misunderstanding after it has spread across several files.
This may be where Mermaid saves me the most tokens. Once the structure is visible, I can point to a component or change an arrow instead of explaining the entire system again in prose. It is the most efficient way I have found to communicate the structure I have in mind.
Different questions need different diagrams
I used to think of a software diagram as a general overview of a system. In practice, one overview is rarely enough.
The useful diagram depends on the question.
- What changes? An as-is and to-be comparison.
- Are the main responsibilities in the right place? A high-level architecture diagram.
- Where does the data come from, and where does it go? A data-flow diagram.
- In what order do components communicate? A sequence diagram.
- Why is this component difficult to reason about? A lifecycle or state diagram.
This is also why the newer tools differ so much.
GitDiagram and CodeBoarding begin with the repository and try to explain what already exists. OpenHop focuses on walking through a particular flow. diagram-design and Archify focus more on how an agent constructs and presents the diagram itself. FlowPeek assumes that the Mermaid source already exists and makes it quicker to inspect.
I do not think one of these approaches will replace all the others. They operate at different points in the same workflow.
Sharing diagrams
Mermaid is also convenient when I need to share a diagram.
Sometimes I render it and send a screenshot. This is usually enough when I want a quick answer or need to discuss a particular part of the design.
At other times, I send the Mermaid source itself through a messenger. The other person can render it, change it, or give it to an agent as context.
I send an image when the diagram only needs to be viewed, and the Mermaid source when it may need to be changed or reused.
The same source can be documentation, input for an agent, and something people exchange during a conversation. I do not need to maintain a separate editable diagram and exported image.
Not every diagram needs to be Mermaid. If presentation quality, interaction, or animation matters, an HTML or SVG-based tool such as diagram-design or Archify may be a better fit. Mermaid is useful to me mainly because it has low friction and travels well between people, agents, Markdown, and source control.
A diagram can still become stale
Keeping a diagram as text does not prevent it from becoming outdated.
A good document can still be forgotten. It can remain in the repository long after the implementation has changed, or be placed somewhere the next agent never looks.
If a diagram should remain useful, the agent needs a reason to read and update it.
That can be as simple as referencing it from AGENTS.md, CLAUDE.md, or the repository’s main documentation. The implementation instructions can also ask the agent to compare its plan with the existing diagram and update the diagram when the architecture changes.
This makes the diagram part of the workflow rather than an artifact produced at the end of it.
For diagrams that only answer a temporary question, I do not think this is necessary. A screenshot in a conversation may be enough. But if a diagram represents an architectural decision that future work depends on, it should live with the code and appear in the agent’s working context.
Diagrams as an intermediate interface
I do not use diagrams to avoid reading code entirely. I use them to decide where to read and what to question.
They are most useful between planning and implementation. At that point, the agent has explored enough of the system to describe its proposal, but changing the proposal is still inexpensive.
This also gives people and agents a shared object to discuss. Instead of reviewing a long explanation and imagining the structure separately, both can refer to the same components and connections.
The recent interest in code visualization seems to be part of this broader change. As agents write more code, we need practical ways to inspect their understanding before inspecting every line of their output.
For me, diagrams are one of those ways.