oh-my-mermaid
omm — Architecture mirror for vibe coding
何を解決するか
oh-my-mermaid（omm）は、AI コーディングツール（Claude Code / Codex / Cursor など）と連携し、コードベースの構造を Mermaid 図 + テキストフィールド で継続的に文書化する CLI ツール。
AI writes code in seconds. Humans understand it in hours.
But skip understanding, the codebase becomes a black box — even to you.
omm はこのギャップを埋める。AI に /omm-scan スキルを実行させると、コードベースから パースペクティブ（複数の視点）が生成され、プロジェクトルートの .omm/ ディレクトリに蓄積される。
7フィールド / 要素
∞ネスト深さ
5+対応 AI ツール
MITライセンス
.omm/ ディレクトリ構造
各パースペクティブはサブディレクトリ。さらにその中に ネスト要素（子ディレクトリ）を持てる。ビュワーはファイルシステムのツリーを自動解析してグループを展開表示する。
.omm/
├── overall-architecture/ ← perspective
│ ├── description.md
│ ├── diagram.mmd
│ ├── context.md
│ ├── cli/ ← nested element
│ │ ├── description.md
│ │ └── diagram.mmd
│ └── server/ ← deeper nesting
│ └── ...
├── data-flow/
└── command-surface/
├── overall-architecture/ ← perspective
│ ├── description.md
│ ├── diagram.mmd
│ ├── context.md
│ ├── cli/ ← nested element
│ │ ├── description.md
│ │ └── diagram.mmd
│ └── server/ ← deeper nesting
│ └── ...
├── data-flow/
└── command-surface/
各要素が持てる 7 つのフィールド:
description
diagram
context
constraint
concern
todo
note
コンポーネント全体像
omm 自身が /omm-scan でスキャンした overall-architecture パースペクティブ。CLI が各コマンドへ振り分け、コマンドはストア・クラウド・解析エンジン群を呼び出す。
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#ede9fe", "primaryTextColor": "#3b1d8c", "primaryBorderColor": "#8b5cf6", "lineColor": "#8b5cf6", "secondaryColor": "#f5f3ff", "tertiaryColor": "#fdf4ff", "fontFamily": "Sora, system-ui, sans-serif", "fontSize": "13px"}}}%%
graph LR
cli["CLI Dispatcher\nsrc/cli.ts"]
commands["Commands\nsrc/commands/"]
store["Store\nsrc/lib/store.ts"]
cloud["Cloud Client\nsrc/lib/cloud.ts"]
diff-engine["Diff Engine\nsrc/lib/diff.ts"]
refs["Ref Tracker\nsrc/lib/refs.ts"]
validator["Validator\nsrc/lib/validate.ts"]
meta["Meta Tracker\nsrc/lib/meta.ts"]
cloud-paths["Cloud Paths\nsrc/lib/cloud-paths.ts"]
platforms["Platform Integrations\nsrc/lib/platforms/"]
server["Web Viewer\nsrc/server/"]
public-api["Public API\nsrc/index.ts"]
cli -->|"dispatches args"| commands
commands -->|"read/write .omm/"| store
commands -->|"push/pull REST"| cloud
commands -->|"compare diagrams"| diff-engine
commands -->|"cross-references"| refs
commands -->|"validate mermaid"| validator
commands -->|"register skills"| platforms
commands -->|"start HTTP server"| server
store -->|"update timestamps"| meta
cloud -->|"safe path resolve"| cloud-paths
server -->|"read classes"| store
server -->|"compare diagrams"| diff-engine
server -->|"resolve refs"| refs
public-api -->|"re-exports"| store
public-api -->|"re-exports"| diff-engine
public-api -->|"re-exports"| refs
public-api -->|"re-exports"| validator
classDef entry fill:#ddd6fe,stroke:#8b5cf6,color:#3b1d8c
classDef store fill:#d1fae5,stroke:#059669,color:#064e3b
class cli,public-api entry
class store store
主要モジュール
| モジュール | ファイル | 役割 |
|---|---|---|
cli.ts | src/cli.ts | 引数パース・コマンドディスパッチ |
store.ts | src/lib/store.ts | .omm/ の読み書き・メタ更新・ネスト管理 |
cloud.ts | src/lib/cloud.ts | ohmymermaid.com REST API クライアント |
diff.ts | src/lib/diff.ts | Mermaid ノード/エッジの差分検出 |
refs.ts | src/lib/refs.ts | 図間クロスリファレンス追跡 |
validate.ts | src/lib/validate.ts | Mermaid 構文・規約バリデーション |
meta.ts | src/lib/meta.ts | created/updated/git_commit メタ管理 |
platforms/ | src/lib/platforms/ | 各 AI ツールへのスキル登録 |
server/ | src/server/ | インタラクティブ Web ビュワー (SSE) |
index.ts | src/index.ts | パブリック API（store/diff/refs/validator を再エクスポート） |
コマンドサーフェス
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#ede9fe", "primaryTextColor": "#3b1d8c", "primaryBorderColor": "#8b5cf6", "lineColor": "#8b5cf6", "secondaryColor": "#f5f3ff", "fontFamily": "Sora, system-ui, sans-serif", "fontSize": "12px"}}}%%
graph TD
omm["omm\nCLI entry"]
omm -->|"local"| init["init\nomm init"]
omm -->|"local"| list["list\nomm list"]
omm -->|"local"| show["show\nomm show <class>"]
omm -->|"local"| delete["delete\nomm delete <class>"]
omm -->|"local"| status["status\nomm status"]
omm -->|"query"| diff["diff\nomm diff <class>"]
omm -->|"query"| refs["refs\nomm refs <class>"]
omm -->|"query"| validate["validate\nomm validate"]
omm -->|"viewer"| view["view\nomm view [--port N]"]
omm -->|"cloud"| login["login\nomm login"]
omm -->|"cloud"| link["link\nomm link [org/slug]"]
omm -->|"cloud"| push["push\nomm push"]
omm -->|"cloud"| pull["pull\nomm pull"]
omm -->|"cloud"| share["share\nomm share"]
omm -->|"cloud"| org["org\nomm org <sub>"]
omm -->|"integration"| setup["setup\nomm setup [platform]"]
omm -->|"integration"| update["update\nomm update"]
omm -->|"rw"| rw["read/write\nomm <path> <field>"]
classDef entry fill:#ddd6fe,stroke:#8b5cf6,color:#3b1d8c
class omm entry
CLI コマンド一覧
| コマンド | カテゴリ | 説明 |
|---|---|---|
omm setup [platform] | integration | AI ツールにスキルを登録。省略時は自動検出 |
omm view [--port N] | local | インタラクティブ Web ビュワーを起動 (default: 3000) |
omm list | local | パースペクティブ一覧表示 |
omm tree <path> | local | 要素ツリーを表示 |
omm show <path> | local | 要素の全フィールドを表示 |
omm status | local | 全要素の概要を表示 |
omm diff <path> | query | 現在と前回の図を比較 |
omm refs <path> | query | クロスリファレンスを表示 |
omm validate [path] | query | Mermaid 構文・規約を検証 |
omm push / pull | cloud | .omm/ をクラウドへ同期 |
omm link [org/slug] | cloud | プロジェクトをクラウド slug に紐付け |
omm share | cloud | 共有 URL を表示 |
omm config language <code> | local | コンテンツ言語を設定（例: ja, ko, zh） |
omm read <path> <field> | local | フィールドを stdout に出力 |
omm write <path> <field> - | local | stdin からフィールドを書き込み |
AI スキル（/ コマンド）
スキルはターミナルではなく AI コーディングツール内 で実行するコマンド。omm setup で登録される。
| スキル | 動作 |
|---|---|
/omm-scan | コードベースを解析し、パースペクティブ駆動の再帰的なアーキテクチャ文書を生成・更新する |
/omm-push | ログイン → リンク → クラウドへプッシュをワンステップで実行 |
パスの形式:
omm write overall-architecture/cli description - <<'EOF' のようにスラッシュで階層を指定。Element IDs は kebab-case で、ディレクトリ名と一致させる。
3 つの主要フロー
omm のデータは 3 経路で流れる: 書き込みパス（AI → store → .omm/）、解析パス（.omm/ → validator/diff/refs）、同期パス（.omm/ ↔ クラウド、Web ビュワー SSE）。
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#ede9fe", "primaryTextColor": "#3b1d8c", "primaryBorderColor": "#8b5cf6", "lineColor": "#8b5cf6", "secondaryColor": "#f5f3ff", "tertiaryColor": "#fdf4ff", "fontFamily": "Sora, system-ui, sans-serif", "fontSize": "12px"}}}%%
graph LR
ai-assistant["AI Assistant\nClaude Code / Codex"]
cli-input["CLI Input\nomm write"]
store-engine["Store Engine\nsrc/lib/store.ts"]
omm-dir[".omm/ Directory\nFilesystem"]
meta-tracker["Meta Tracker\nsrc/lib/meta.ts"]
validator["Validator\nsrc/lib/validate.ts"]
diff-engine["Diff Engine\nsrc/lib/diff.ts"]
ref-tracker["Ref Tracker\nsrc/lib/refs.ts"]
cloud-api["Cloud API\nohmymermaid.com"]
web-viewer["Web Viewer\nlocalhost:3000"]
credentials["Credentials\n~/.omm/credentials.json"]
ai-assistant -->|"omm write"| cli-input
cli-input -->|"writeField()"| store-engine
store-engine -->|"field files"| omm-dir
store-engine -->|"save prev_diagram"| omm-dir
store-engine -->|"updateMeta()"| meta-tracker
meta-tracker -->|"meta.yaml + git info"| omm-dir
omm-dir -->|"readField()"| store-engine
store-engine -->|"diagram text"| validator
store-engine -->|"diagram text"| diff-engine
store-engine -->|"diagram text"| ref-tracker
omm-dir -->|"push all files"| cloud-api
cloud-api -->|"pull files"| omm-dir
credentials -->|"Bearer token"| cloud-api
omm-dir -->|"fs.watch + SSE"| web-viewer
web-viewer -->|"REST reads"| store-engine
classDef ext fill:#e2e8f0,stroke:#94a3b8,color:#334155
classDef entry fill:#ddd6fe,stroke:#8b5cf6,color:#3b1d8c
classDef storage fill:#d1fae5,stroke:#059669,color:#064e3b
class ai-assistant,cloud-api ext
class cli-input entry
class omm-dir,credentials storage
書き込みパス詳細
AI が omm write 実行
→
cli.ts でコマンド解析
→
writeNodeField()
→
prev_diagram を meta.yaml に保存
→
field file 書き込み
→
meta.yaml 更新（created / updated / git_commit）
→
親要素の children リスト更新
meta.yaml は created, updated, update_count, last_field, git_commit, prev_diagram, children などを保持し、omm diff や変更履歴追跡に利用される。
ohmymermaid.com
.omm/ をクラウドに同期することで、チーム共有や公開 URL の発行が可能になる。認証トークンは ~/.omm/credentials.json（パーミッション 0600）に保存される。
omm login # ブラウザ認証
omm link myorg/my-project # プロジェクトを slug に紐付け
omm push # .omm/ をアップロード
omm share # 共有 URL を表示
omm pull # クラウドから取得デフォルトは プライベート。公開共有リンクは omm share で取得できる（例: ohmymermaid.com/share/…）。
組織管理
| コマンド | 説明 |
|---|---|
omm org list | 所属組織の一覧 |
omm org switch <slug> | デフォルト組織を切り替え |
omm org members [slug] | メンバー一覧をブラウザで表示 |
Cloud Paths:
src/lib/cloud-paths.ts がパスの安全な解決を担当し、ディレクトリトラバーサルを防ぐ。
インストールと初回スキャン
# 1. インストール
npm install -g oh-my-mermaid
# 2. AI ツールへスキルを登録
omm setup # 全ツールを自動検出
omm setup cursor # Cursor に限定
# 3. AI ツール内でスキャン実行
/omm-scan
# 4. ブラウザでビュワーを開く
omm view
対応 AI ツール
| プラットフォーム | セットアップコマンド |
|---|---|
| Claude Code | omm setup claude |
| Codex | omm setup codex |
| Cursor | omm setup cursor |
| OpenClaw | omm setup openclaw |
| Antigravity | omm setup antigravity |
Web ビュワー
omm view で localhost:3000 にインタラクティブな Web ビュワーが起動する。fs.watch + SSE でファイルの変更を検知しリアルタイムに更新。Mermaid 図はクリックで展開・縮小でき、ネストされた子要素をインタラクティブに探索できる。
# カスタムポートで起動
omm view --port 8080
# バージョン確認
omm --version
# 更新
omm update
参考リンク
- npm: oh-my-mermaid
- GitHub: oh-my-mermaid/oh-my-mermaid
- ohmymermaid.com — クラウドサービス
- Mermaid.js — 図の記述言語