Turn complex codebases into clear, navigable architecture diagrams with Claude Code.

Oh-my-mermaid

AI writes code in seconds. Humans understand it in hours.
But skip understanding, the codebase becomes a black box — even to you.

omm closes the gap — architecture docs, generated by AI, for humans.

Quick Start

Paste this in your terminal:

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

Then open your AI coding tool and use the /omm-scan skill:

/omm-scan

That’s it. View the result:

omm view

Example

omm scanned itself. This is what it found.

How It Works

Your AI analyzes the codebase and generates perspectives — different lenses on your architecture (structure, data flow, integrations…). Each perspective contains a Mermaid diagram and documentation fields.

Every node gets recursively analyzed. Complex nodes become nested child elements with their own diagrams. Simple ones stay as leaves. The filesystem reflects the tree:

.omm/
├── overall-architecture/           ← perspective
│   ├── description.md
│   ├── diagram.mmd
│   ├── context.md
│   ├── main-process/               ← nested element
│   │   ├── description.md
│   │   ├── diagram.mmd
│   │   └── auth-service/           ← deeper nesting
│   │       └── ...
│   └── renderer/
│       └── ...
├── data-flow/
└── external-integrations/

The viewer auto-detects nesting from the filesystem — elements with children render as expandable groups, others as nodes.

Each element carries up to 7 fields: description, diagram, context, constraint, concern, todo, note.

CLI

omm setup                          # Register skills with your AI tools
omm view                           # Open interactive viewer
omm config language ko             # Set content language
omm update                         # Update to latest version

Run omm help for the full command list.

Skills

Skills are commands you run inside your AI coding tool (not the terminal). They start with /.

Skill	What it does
`/omm-scan`	Analyze codebase → generate architecture docs
`/omm-push`	Login + link + push to cloud in one step

Cloud

You can store your architecture in the cloud via ohmymermaid.com.

omm login && omm link && omm push

It’s private by default. Share with your team, or make it public like this example.

Supported AI Tools

Platform	Setup
Claude Code	`omm setup claude`
Codex	`omm setup codex`
Cursor	`omm setup cursor`
OpenClaw	`omm setup openclaw`
Antigravity	`omm setup antigravity`

Run omm setup to auto-detect and configure all installed tools.

Roadmap

See docs/ROADMAP.md.

Development & Contributing

git clone https://github.com/oh-my-mermaid/oh-my-mermaid.git
cd oh-my-mermaid
npm install && npm run build
npm test

Issues and PRs welcome. Use Conventional Commits.

License

MIT