I recently built a small CLI called readable-mermaid. It takes a Mermaid sequence diagram .mmd file — and only sequence diagrams — and outputs a doc-ready diagram image with readable font sizes, proper spacing, and staggered headers. Mermaid’s native output is nearly unreadable once diagrams get complex.
While wrapping up the project, writing the README and thinking about how to describe it, something clicked that I hadn’t noticed during development:
I built this entire thing for AI. Not for a person.
The workflow is: an AI assistant generates a Mermaid sequence diagram as part of writing a design document, calls readable-mermaid to render it, and the output goes straight into the doc. The engineer never runs the command. They probably never even learn its name. They just get a diagram they can actually read.
What’s strange is that a human still benefits. Someone will look at the diagram and understand the architecture. But that person has no relationship with the tool that made it. They’re downstream of a process they never see.
This was a completely new experience for me. For the first time, I wasn’t using AI — I was working for it.
In a way, this isn’t new at all. Writing a utility that gets called by other software is one of the most ordinary things a developer does. But even then, a human always decided where to put the call — someone wrote the line of code that invoked the function. With readable-mermaid, the AI decides on its own that it needs this tool. Right now I still nudge it: a line in a config file that says “when you generate a Mermaid diagram, use this.” But the AI is the one interpreting that, choosing when to act on it, and running the command.
readable-mermaid only handles sequence diagrams. That sounds narrow, but I think that’s exactly right. The tool is fully deterministic — same input, same output, every time. It doesn’t need judgment, creativity, or context. It just needs to run. In the same way we write small, single-purpose functions in code, tools for AI work best when they do one thing and do it reliably. The AI handles the judgment: deciding when a diagram needs to be readable. The tool handles the mechanical part.
I don’t have a grand theory about what this means for software development. I just know it felt different. This time, the human is not the user — just the beneficiary.
It’s a small thing. But it made me look at my work a little differently.