oh-my-mermaid: Claude Code skills that turn a codebase into nested Mermaid architecture docs

The problem omm targets: code written faster than it can be read

The README opens with a blunt framing: AI writes code in seconds, humans understand it in hours. That is the gap oh-my-mermaid claims to close. The target user is not someone documenting a legacy system they already understand. It is a developer who let an AI agent write a large amount of code and now cannot hold the resulting structure in their head. The output is architecture documentation, described in the README as generated by AI, for humans. The unit of output is a perspective, which the README defines as a lens on your architecture such as structure, data flow or integrations. Each perspective carries a Mermaid diagram plus documentation fields, so the diagram is not the whole artifact. That distinction matters: a diagram alone tells you boxes and arrows, while the surrounding fields are where constraints and open questions are supposed to live. If you only want a picture, this is more machinery than you need.

How omm works: AI-generated perspectives written to a .omm filesystem tree

The mechanism is unusual. omm does not parse your source into an AST and emit a graph. Your AI tool analyzes the codebase and generates the perspectives. The CLI and the skills are the scaffolding around that analysis. Every node gets recursively analyzed, per the README. Complex nodes become nested child elements with their own diagrams, while simple ones stay as leaves. The filesystem is the data model, and the README shows the layout directly: a perspective directory holds description.md, diagram.mmd and context.md, and nested element directories repeat that shape. The viewer auto-detects nesting from the filesystem, so elements with children render as expandable groups and the rest as nodes. Each element carries up to 7 fields: description, diagram, context, constraint, concern, todo, note. Two consequences follow. First, the tree is diffable and reviewable like any other file in the repository. Second, the quality of the whole artifact depends on the model doing the analysis, and the README documents no validation step that would catch a diagram that contradicts the code.

Installing oh-my-mermaid and running a first /omm-scan

The README gives a one-line install that also registers the skills. Run it from your terminal; the package requires Node 18 or newer according to package.json.

npm install -g oh-my-mermaid && omm setup

The setup command auto-detects installed AI tools and configures them, or you can name one explicitly. The README lists Claude Code, Codex, Cursor, OpenClaw and Antigravity as supported platforms.

omm setup claude

Skills are commands you run inside your AI coding tool, not in the terminal, and they start with a slash. The scan skill is the one that produces the documentation.

/omm-scan

When the scan finishes, the viewer opens the result. The README notes that omm scanned itself and the screenshots in docs/ come from that run.

omm view

Two smaller commands are worth knowing on day one. The content language of generated documentation can be changed, and the CLI has a self-update path.

omm config language ko
omm update

Run omm help for the full command list. If you want the tree stored remotely rather than only on disk, the README documents a three-step flow: omm login, omm link, omm push, or the single /omm-push skill. The README states the cloud copy is private by default.

Where oh-my-mermaid breaks down

The dependency on an AI coding tool is the first limitation, and it is structural rather than incidental. There is no documented mode that generates perspectives without one. That rules out a CI job on a machine with no configured assistant, and it means two developers scanning the same commit can get different trees. Nothing in the README describes a canonical output or a check that would flag drift. The second limitation is scale. Recursive analysis of every node sounds thorough, and it is the reason the tree is useful, but it also means cost and time grow with the number of nodes the model decides are complex. The README gives no guidance on bounding that recursion, no file-count threshold, and no way to mark a directory as out of scope. Third, the seven fields are only as good as the model that fills them. A constraint or concern field that contains a plausible-sounding guess is worse than an empty one, because it reads as documentation. The README does not describe how these fields are validated, and there is no stated review workflow. Finally, the cloud path introduces a dependency on ohmymermaid.com that the local-only workflow does not have; if you only need files in the repository, skip omm login entirely.

oh-my-mermaid versus Mermaid CLI and hand-written diagrams

The obvious alternative is the Mermaid CLI toolchain: you write .mmd files yourself or generate them from a static analyzer, then render them in CI. The difference in approach is where the meaning comes from. With Mermaid CLI, the diagram is authored or derived by deterministic rules, so the same input always yields the same output, and a diff in the .mmd file is a diff in something a human wrote. With oh-my-mermaid, the diagram is an interpretation produced by a language model reading the code, which is why the tool can describe intent, constraints and open questions that no parser could extract. You are trading reproducibility for coverage. A static analyzer will never tell you that a service looks like it is doing two jobs; a model will, and it may be wrong. The nested-tree layout is the other real difference: oh-my-mermaid keeps child diagrams on disk under the parent element, so depth is navigable in a file browser. A flat set of hand-written .mmd files has no equivalent structure unless you impose one. If your diagrams must be regenerated identically on every commit, the Mermaid CLI route is the honest choice.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-04-07. The most recent release listed is v0.2.0 from 2026-03-25, with v0.1.8 and v0.1.7 landing the day before it. That clustering suggests small, quick releases rather than a long stabilization cycle. The runtime dependency list in package.json contains a single entry, yaml, which keeps the install surface small and the upgrade risk low for consumers. The CLI ships an omm update command, so upgrading does not require remembering the npm invocation. Because the package is published to npm with a bin entry named omm, version pinning works the way it does for any global npm tool. The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained; the LICENSE file is included in the published package files list. This is a description of the licence text, not legal advice, and the cloud service at ohmymermaid.com is a separate matter from the MIT-licensed code, so read its terms before pushing an architecture tree to it.

Editorial conclusion

Adopt oh-my-mermaid if your team already works inside Claude Code, Codex, Cursor, OpenClaw or Antigravity and wants architecture documentation that lives as plain files next to the code. Do not adopt it if you need diagrams produced in CI without an AI tool, or if you want a static analyzer whose output is reproducible byte for byte. Before committing, run the scan on one mid-sized package, read the generated .omm tree, and decide whether the seven per-element fields are filled with anything you would actually keep in review. The last push to the repository was on 2026-04-07, so check the issue tracker for how quickly the single-dependency runtime is being kept current.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oh-my-mermaid/oh-my-mermaid on GitHub
4. README
5. Releases