oh-my-mermaid: filesystem-backed architecture diagrams generated by your AI coding tool
Turn complex codebases into clear, navigable architecture diagrams with Claude Code.
At a glance
- What is it?
- oh-my-mermaid (omm) is an MIT-licensed TypeScript CLI that turns an AI coding tool into an architecture diagram generator. It writes Mermaid diagrams and markdown notes into a .omm/ folder, and the depth of that folder tree is decided by the model, not by a schema.
- Who is it for?
- Adopt omm if your codebase is already too large for one person to hold in their head and you want architecture notes that live next to the code as plain markdown and .mmd files you can edit by hand. Skip it if you need diagrams that stay correct automatically, because /omm-scan is a manual, model-driven pass and nothing in the README describes drift detection or CI enforcement.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 162 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap omm targets: code written fast, understood slowly
The README states the problem in one line: AI writes code in seconds, humans understand it in hours. That framing points at a specific failure mode. When an agent adds a service, a queue consumer or a new integration, the diff is reviewable but the resulting shape of the system is not. Nobody drew the box and the arrow. Over enough sessions the codebase becomes, in the project's own words, a black box even to the person who owns it.
omm is aimed at that person: a developer working in an AI coding tool who wants a diagram of what the tool just built. It is not a static analysis engine and it is not a documentation site generator. It is a thin convention (a folder layout, a set of markdown field names, a viewer) wrapped around a skill that your AI tool executes. The intelligence is the model's; omm supplies the structure and the rendering.
Perspectives, recursion, and a folder tree that is the diagram
The core abstraction is the perspective. According to the README, the AI generates perspectives, described as different lenses on the architecture, with structure, data flow and integrations given as examples. Each perspective holds a Mermaid diagram plus documentation fields.
The second mechanism is recursion. Every node is analyzed again. Complex nodes become nested child elements with their own diagrams, and simple ones stay as leaves. The result is written to disk, and the filesystem is the tree:
.omm/overall-architecture/ contains description.md, diagram.mmd and context.md, alongside subfolders such as main-process/ and renderer/, each of which repeats the same file pattern and can nest further. Sibling perspectives such as data-flow/ and external-integrations/ sit at the same level.
This is the design decision worth pausing on. The viewer does not read a manifest to learn the hierarchy. It auto-detects nesting from the filesystem, so an element with children renders as an expandable group and an element without children renders as a node. That makes the format inspectable and diffable with ordinary tools, and it also means the folder structure is authoritative. Rename a directory and you have renamed a node.
Each element carries up to seven fields: description, diagram, context, constraint, concern, todo and note. Only description and diagram appear explicitly in the documented tree, so the other five are optional. That is a reasonable split. Concern and todo are the fields that make this more than a picture: they give the model somewhere to record what it could not explain or what looks unfinished, which is often the most useful output of an architecture pass.
Getting it running: three commands and a skill
The README gives a single-line quick start:
npm install -g oh-my-mermaid && omm setup
Then, inside your AI coding tool rather than the terminal, you run the skill:
/omm-scan
And to see the result:
omm view
Setup is per tool if you prefer to be explicit. The supported table lists omm setup claude, omm setup codex, omm setup cursor, omm setup openclaw and omm setup antigravity, and running omm setup with no argument auto-detects and configures all installed tools. The other CLI surface documented is small: omm config language ko sets the content language, omm update updates the package, and omm help lists the rest. A second skill, /omm-push, handles login, link and push to the hosted service in one step.
Two details matter more than they look. First, the skills are slash commands executed by the AI tool, not shell commands, so the quality of the scan depends on the model and on how much of the repository it chooses to read. Second, omm config language takes a language code, which tells you the generated prose is templated per locale rather than written in whatever language you happen to be speaking. If your team writes in one language and reads diagrams in another, that setting is the one to check first.
The cloud path and what it changes about privacy
Architecture output can stay local, or it can go to ohmymermaid.com. The documented sequence is omm login && omm link && omm push. The README states it is private by default and that you can share with your team or make it public, pointing at a share URL under ohmymermaid.com/share/.
There is no description in the supplied material of what the cloud stores, how long it keeps it, whether the .omm/ folder is uploaded verbatim, or what the sharing model looks like beyond a public link. For a tool whose input is a map of your internal services and integrations, that is the largest unknown in the project. Treat the local .omm/ folder as the default and the cloud as an opt-in you evaluate separately.
Where omm is the wrong tool
The scan is a snapshot. Nothing in the README describes a watcher, a hook, or a check that fails when the code moves and the diagram does not. So the artifacts age the moment someone merges. Teams that want diagrams to stay true without human effort should look at generated-from-source approaches instead, where the graph is derived from imports or infrastructure definitions on every build and cannot drift by construction. The trade is that such tools only draw what is mechanically extractable, which is exactly the layer omm is trying to go beyond.
The second limitation is the recursion. Depth is the model's judgement, not a configured limit. The documented tree shows nesting reaching at least three levels (perspective, element, deeper element), but there is no config key in the README for maximum depth or for excluding paths. On a monorepo with hundreds of packages, the number of generated folders is therefore unpredictable before you run it, and the cost of a scan that goes too deep is paid in review time.
The third is that this is a Claude Code skill first. The README lists five supported tools, but the repository description names Claude Code specifically, and the setup table is the only evidence of parity across the others. If you are not on one of those five, omm has nothing to offer you.
Alternatives and the difference in mechanism
The honest comparison is with documentation-as-code tools that render diagrams from text you maintain yourself, such as Mermaid embedded directly in markdown or in a docs site. The difference is who writes the diagram. With hand-authored Mermaid you decide the nodes and the arrows, and the diagram is as accurate as your last edit. With omm the model proposes the structure and you correct it. That is a real gain on an unfamiliar codebase and a real loss on a small one, where writing twenty lines of Mermaid takes less time than reviewing a generated tree.
The second comparison is with architecture-diagram tools that parse the repository. Those derive edges from actual code relationships, so an unimported module cannot appear as a dependency. omm derives edges from a model reading files, which means it can surface intent and constraints that no parser can infer, and can also state a relationship that does not exist. The README's constraint, concern and todo fields are the mitigation: they are where uncertainty is supposed to land.
Maintenance cost, versioning and the MIT licence
The release history supplied shows v0.1.7 and v0.1.8 on 2026-03-24 and v0.2.0 on 2026-03-25, with the last push to the default branch on 2026-04-07. Three releases inside two days, then a minor bump, is the shape of a young project moving quickly. Expect the .omm/ layout and the skill names to be the parts most likely to shift, because they are the interface between the tool, the AI and your repository.
Upgrading is handled by omm update, and the generated content is plain files, so a format change is something you would see as a diff in .omm/ rather than as a migration script. The practical cost is not the upgrade command; it is re-running /omm-scan after a format change if you want the tree to match the current conventions.
The project is MIT licensed, which permits commercial use and modification, and the README links the LICENSE file as the source of truth. The hosted service at ohmymermaid.com is a separate thing from the code and its terms are not described in the material supplied, so the licence on the repository tells you nothing about the cloud terms. That is a question for the service, not for the LICENSE file.
Editorial conclusion
Adopt omm if your codebase is already too large for one person to hold in their head and you want architecture notes that live next to the code as plain markdown and .mmd files you can edit by hand. Skip it if you need diagrams that stay correct automatically, because /omm-scan is a manual, model-driven pass and nothing in the README describes drift detection or CI enforcement. Before committing to it, run omm setup, then /omm-scan on a single package, and inspect the .omm/ tree: if the recursion depth and the seven optional fields come back thin or wrong, the cost of correcting them by hand is the real price of the tool.
Community notes