Visual Explainer: ターミナルアートからHTMLダイアグラムへ
Visual Explainer: ターミナルアートからHTMLダイアグラムへ
はじめに
多くの開発者は複雑なターミナル出力をプレーンテキストで印刷し続けていますが、ASCIIアートやパイプ区切りの表はすぐに読めなくなります。Visual Explainer は、任意のターミナル図、コード差分、計画レビューを、ダーク/ライトテーマ、インタラクティブなMermaidチャート、レスポンシブスライドデッキ付きの洗練された自己完結型 HTML ページへ変換します。
問題点
- ターミナルの ASCII アートは単体ボックスのフローチャートでは機能しますが、複数ボックスの図では崩れます。
|と-で描かれた表はターミナルでは見栄えが良いですが、エクスポートや共有時に折り返しや崩れが起こります。- 生の diff 出力からプレゼンテーションやドキュメントを作成するのは時間がかかり、エラーが生じやすいです。
解決策
Visual Explainer は、混乱したターミナル出力を構造・スタイリング・インタラクティブ性を保持したブラウザ対応ページに置き換えます。複雑なデータをダンプしていると自動で検出し、最適な HTML 表現をレンダリングする便利なスラッシュコマンドを数種類同梱しています。
主な機能
| Feature | Description |
|---|---|
/diff-review |
変更前後のアーキテクチャ図、KPI ダッシュボード、構造化された Good/Bad/Ugly コードレビューを含むビジュアル diff レビューを生成します |
/plan-review |
計画ファイルをコードベースと交差参照し、リスクをフラグ付け、現在と計画のアーキテクチャ図を作成します |
/generate-web-diagram |
例: 「認証フローの図を描いて」といった任意のテーマを独立した HTML ページに変換します |
/generate-slides |
プロンプトをマガジン品質のスライドデッキに変換し、オプションで --slides フラグをサポートします |
/project-recap |
プロジェクトの最近のアクティビティをスナップショットし、アーキテクチャ、意思決定ログ、コグニティブデットのホットスポットを表示します |
/fact-check |
文書内の主張を実際のコードと照合して検証します |
すべてのコマンドは同じ基盤ワークフローを呼び出します。スキルはリクエストを解析し、適切なレファレンステンプレートを選択、references/ フォルダから必要データを取得し、~/.agent/diagrams/ に HTML ファイルを書き込みます。ページは自動的に既定のブラウザで開きます。
インストール
すでに pi ユーザーであれば、インストールは次の一行です。
pi install https://github.com/nicobailon/visual-explainer
Claude Code や他のエージェントのユーザーには、スキルディレクトリにクローンするだけです：
git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer
ビルドステップは不要です。ツールはブラウザと、オプションで surf-cli バイナリ（画像生成用）にのみ依存します。
スキルの使用
簡単なデモ：
generate-web-diagram
draw a diagram of our authentication flow
スキルは Mermaid ダイアグラムをレンダリングし、ライト/ダークテーマを適用し、~/.agent/diagrams/auth-flow.html をブラウザで開きます。
最近のプルリクエストをレビューするには：
diff-review #42
defaultでは /diff-review は現在のブランチを main と比較します。任意のリファレンスを渡すことも可能です：
diff-review abc123 # 単一コミット
diff-review main..HEAD # ステージ済みコミット全て
diff-review main..dev-feature # ブランチ全体
スライドデッキを作成したい場合は --slides フラグを付けてください：
diff-review --slides
カスタマイズ
- テーマとレイアウト –
references/css-patterns.mdの CSS ファイルを編集してパレットを選択、またはアニメーションを調整します。 - テンプレート –
templates/内の 4 つのテンプレート（例：architecture.html、data-table.html）を入れ替えるか、自作してください。 - 出力先とブラウザ –
SKILL.mdの変数を変更してファイルを書き込む場所や起動方法を変えます。
スキルは毎回テンプレートをリロードするため、エージェントを再起動せずに迅速に反復できます。
制限とトレードオフ
- インラインターミナル描画なし – 結果はブラウザで開きます。ターミナル内で見ることはできません。
- テーマ切替はページリフレッシュが必要 – Mermaid SVG は OS のテーマ変更に自動的に適応しません。
- モデル依存の品質 – 視覚出力は基盤となる LLM が Mermaid や CSS を生成できるかに左右されます。
これらの欠点にもかかわらず、Visual Explainer は生のテキストを意味のあるビジュアルアーティファクトへ変換する際の摩擦を大幅に減らします。
コミュニティとサポート
リポジトリは積極的にメンテナンスされ、anti‑slop ガードレール (v0.3.0) など定期的に更新されます。Issue、機能リクエスト、プルリクエストは GitHub で受け付けています。3.3 k のスターは、業務図から正式ドキュメントまで幅広い用途でツールを活用する開発者コミュニティの拡大を示しています。
結論
Visual Explainer は、ノイズの多いターミナル出力を洗練された HTML ページやスライドデッキへ変換する軽量でオープンソースの開発者ユーティリティです。数つのスラッシュコマンドで、アーキテクチャ図、diff レビュー、計画監査、プレゼンテーションデッキを自動生成しつつ、エージェント環境内でワークフローを維持できます。ぜひお試しください。コードベースから受け取る視覚的明瞭さを取り戻しましょう。