Orrery

上の図は docs/hero.yaml です。40 行の YAML を orrery がデフォルトの stage スキンでレイアウトして描画しています。まずグループが光り、次にタイルが光ります。その後、彗星の尾を引くパケットがメイン経路を順に進み、ループしながら通過した線を照らします。この README の画像はすべて stage スキンです。skin: classic（または --skin classic）を指定すると、同じレイアウトを各ベンダー独自の図のスタイルで描画し、すべてのエッジに沿ってパケットが流れます。GitHub ではアニメーションが維持され、同じ仕様から生成した PNG は静止画になります。

得られるもの

• 公式の最新アイコンのみ。 18,209 個のアイコンを収録しています。AWS（810 個）、Azure（636 個）、Google Cloud（233 個）、Kubernetes（40 個）、GitHub Octicons（399 個）、IBM Carbon（2,776 個）に加え、技術ロゴ 5,502 個、中立的なシンボル 6,286 個、システム設計やビジネスフローに使える 6 種類のウェイトの Phosphor（1,527 個）を収録しています。独自の SVG も local: アイコンとして使用でき、orrery icons new で作成し、icons check で検証できます。クラウドのアイコンパックは各ベンダーの公式ダウンロードから再構築され、チェックサムで固定されています。Google Cloud の製品には、Google の 2026 年版ガイドで指定されたアイコンが割り当てられます。非推奨のセットや、クラウドアイコンの非公式な描き直しは含まれていません。
• 公式の規約に準拠。 AWS のグループは AWS Architecture Icons デッキ（境界線、破線、コーナータイル、ラベルの配置、塗りつぶしのない矢印の先端、番号付きコールアウト）に従っています。Google Cloud と Azure のグループは、それぞれの参照図に基づいて寸法を測定しています。すべての値の出典は styles.md に記載されています。
• ビジネスフローにも対応。 kind: を使うと、同じ仕様から ISO 5807 フローチャート、プール、レーン、メッセージフローを備えた BPMN 2.0 プロセス、UML ステートマシン、組織図、左右に展開するマインドマップ、感情曲線付きのカスタマージャーニーマップを作成できます。ステージスキンでは、プロセスは BPMN トークンとして再生されます。並列ゲートウェイで分岐し、合流地点で待機してから、はいの分岐へ進みます。
• データモデル、シーケンス、ロードマップ。 kind: er は、型とキーを指定した行を持つテーブルと、接続先の行にぴったり合うカラスの足記法のリレーションシップを描画します。orrery import sql を使うと、CREATE TABLE 文から作成を開始できます。kind: sequence は、メッセージごとに呼び出しフローを描画し、返信は破線、アクティベーションバーとループまたは alt フラグメントも表示して、順番に再生します。kind: timeline は、月、四半期、年単位のロードマップを描画します。レーン、ステータス別のスタイルを適用したバー、マイルストーン、依存関係の矢印、今日を示すマーカーが含まれます。
• 自動レイアウトを自在に調整。 Eclipse Layout Kernel は、入れ子になった境界を配置し、エッジを直角に引き回し、ファンインとファンアウトを幹線にまとめます。また、エッジが交差しない限り、記述した順序を保ちます。座標を指定する必要はありません。配置を調整するには、rank: first、align: <node>、グループの cols: 2、layout: { aspect: 4:3 } を使います。ノードのフロー内の位置を固定したり、ノードを整列させたり、グループ内の子要素をグリッド状に配置したり、README で読みやすいコンパクトな図にしたりできます。
• 1 つの仕様から複数の図を作成。 views: を使うと、1 つのソースから概要と詳細を描画できるため（render --view all）、図同士の内容が食い違いません。classes: でプリセットを共有し、include: で全図に共通のフレームを取り込み、tags: でタグ付けした要素の色やスタイルを変更できます。それぞれに凡例の行が付加されます。
• コードに忠実な図。 orrery import は、Terraform、CloudFormation、CDK の出力、Docker Compose、Kubernetes マニフェスト、Mermaid から仕様を作成します。各ノードには、出典となるファイル、行、識別子を記した evidence: が含まれます。証拠が存在しなくなると orrery verify は失敗し、--link を指定すると各ノードがコミットに固定されたコードへのリンクになります。orrery diff は 2 つのバージョン間の変更を色付きの図で表示し、GitHub Action はレビューとともに、すべてのプルリクエストに投稿します。
• 動きのある図。 デフォルトではアニメーション付き SVG です。パケットはすべてのエッジを同じ速度で進み、メインパスはストーリーとして再生され、線のスタイルは描画時のまま保たれます。流れる破線には animate: flow を、静止画ファイルには --static を指定します。
• 2 種類のスキン、1 つのレイアウト。 デフォルトの stage スキンでは、すべての図をアニメーション付きのシーンとして描画します。デフォルトはダークです。単色の細いグリッド、それぞれのベンダーカラーを控えめに反映したアイコンタイル、モノスペースの大文字ラベル、暗めの配線、それに沿って再生される 1 つのストーリーが特徴です。skin: classic（または --skin classic）を指定すると、各ベンダー独自の図のスタイルに従い、AWS、Azure、Google Cloud のデッキに合わせる必要があるドキュメントに適しています。位置はそのまま維持されます。ダークとライトに対応しています。
• 1 つの仕様から 8 種類の出力。 README やドキュメント向けの SVG、スライドやチャット向けの PNG（デフォルトは 3 倍の解像度で、拡大しても鮮明です）、編集を続けられる .drawio、どこでも画像として表示でき、draw.io で編集可能な図として開ける .drawio.svg、React サイト向けの TSX コンポーネント、ダークモード、パン、ピンチズームに対応した単独の HTML ビューアー、Mermaid のみを描画する Wiki 向けの Mermaid テキスト、メインパスのシーケンス図を出力できます。すべての SVG と PNG には仕様が埋め込まれているため、orrery import picture で画像を編集可能な図に戻せます。orrery doc は図を HTML、Markdown、Word 形式の設計ドキュメントに挿入します。
• エージェント向け。 クイックスタートと作成ルールを備えたスキル、JSON Schema、482 個の短いエイリアス（aws:s3、azure:aks、k8s:deploy、generic:invoice や generic:approval などのビジネス名）、ランキング付きのアイコン検索、対象と修正方法をすべての指摘に記すバリデーター、スキルを使わないクライアント向けの MCP サーバー、コードから図を計画してコードとの整合性を確認するエージェントを用意しています。
• インストール不要。 CLI、レイアウトエンジン、PNG レンダラー、フォント、公式クラウドパックはスキルフォルダーに同梱されています（9 MB）。ロゴとグリフのセットは同梱されず、図で初めて使用されるときに各自の npm ライブラリから読み込まれます。チェックサムで検証され、キャッシュされます。必要なのは Node.js 22 以降だけです。

仕組み

インストール

Claude Code プラグイン：

/plugin marketplace add Sagargupta16/orrery
/plugin install orrery@orrery

Agent Skills を読み込めるエージェント（Codex、Cursor、Gemini CLI、Kiro など）：

npx skills add Sagargupta16/orrery
gh skill install Sagargupta16/orrery orrery              # GitHub CLI, any supported agent
gemini extensions install https://github.com/Sagargupta16/orrery   # Gemini CLI extension

CLI のみを npm からインストールする場合：

npx @sagargupta1610/orrery doctor
npx @sagargupta1610/orrery render diagram.yaml -f all --theme both

または、クローンから実行します：node orrery/skills/orrery/scripts/orrery.mjs doctor。

MCP サーバーとして、Model Context Protocol を使用する任意のクライアント向け（ツール：作成ガイド、検証、レンダリング、レビュー、アイコン検索、テンプレート、パッチ候補、draw.io リンク）：

{ "mcpServers": { "orrery": { "command": "npx", "args": ["-y", "@sagargupta1610/orrery", "mcp"] } } }

このブロックは、Claude Code では .mcp.json、Gemini CLI では ~/.gemini/settings.json、Cursor では .cursor/mcp.json、Kiro では .kiro/settings/mcp.json に記述します。Codex では ~/.codex/config.toml に [mcp_servers.orrery]、command = "npx"、args = ["-y", "@sagargupta1610/orrery", "mcp"] を記述します。orrery mcp install <client> を実行すると、このエントリーが書き込まれます（claude-code、claude-desktop、cursor、vscode、gemini、codex、kiro のいずれかを指定し、プロジェクト単位で設定するか、user を指定してすべてのプロジェクトに設定できます）。ファイル内のほかのサーバー設定は保持されます。リリースごとに、サーバーは MCP Registry に io.github.Sagargupta16/orrery として公開され、Claude Desktop からワンクリックでインストールできる .mcpb バンドルも添付されます。MCP Apps に対応するホストでは、レンダリングされた図がインラインビューアーで開きます。orrery mcp --port 8765 を実行すると、同じツールが 127.0.0.1 上で HTTP 経由で提供されます。仕様はテキストとして渡され、ディスクからの読み込みやディスクへの書き込みは行われません。

クイックスタート

エージェントに図を依頼します（「このリポジトリのアーキテクチャを描いて」「AWS の 2 つのアベイラビリティーゾーンにまたがる 3 層 Web アプリ」「この Mermaid フローチャートを Google Cloud の図に変換して」など）。仕様を作成し、検証してレンダリングした後、図をチェックします。または、自分で作成することもできます。

title: Orders API
direction: right
groups:
  cloud:  { type: aws:cloud }
  region: { type: aws:region, label: eu-west-1, in: cloud }
nodes:
  users: { icon: aws:users, label: Customers }
  api:   { icon: aws:api-gateway, in: region }
  fn:    { icon: aws:lambda, label: Create order, in: region }
  table: { icon: aws:dynamodb, label: Orders, in: region }
edges:
  - users -> api: HTTPS
  - api -> fn -> table

node skills/orrery/scripts/orrery.mjs render orders.yaml -f svg,png

ラベルはデフォルトで公式サービス名になるため、{ icon: aws:lambda } は「AWS Lambda」と表示されます。エッジでは矢印を使います：-> は実線、--> は破線、..> は点線、==> は太線、<-> は双方向、a -> b, c は分岐です。形式の詳細は spec.md を参照してください。

例

aws-three-tier：AWS の 2 つのアベイラビリティーゾーンにまたがる VPC に、パブリック、Web、データの各サブネットと、両方のゾーンにまたがって描画された Auto Scaling グループを配置し、AWS デッキ独自のグループスタイルを使用しています。

これは 77 個ある参考図の 1 つです。AWS（Bedrock AgentCore 上のエージェントから、災害復旧、脅威検出、ネットワーク検査、移行、コンタクトセンターまで）、Azure、Google Cloud、IBM Cloud、Kubernetes、AI と ML、データプラットフォーム、CI/CD、C4、システム設計、ビジネスフロー（フローチャート、BPMN プロセス、スイムレーン、ステートマシン、組織図、マインドマップ、カスタマージャーニー）を扱っています。それぞれの図は skills/orrery/examples 内の仕様からレンダリングされ、CI によってレンダラーとの整合性がチェックされています。すべての図をライトモードとダークモードで閲覧でき、仕様と各種出力をダウンロードできます。sagargupta.online/orrery/gallery、または各図のレンダリングコマンドを掲載した examples/README.md をご覧ください。orrery init <name> を実行すると、どの図もひな形としてコピーできます。

修正方法もわかる検証

$ orrery validate orders.yaml
error DG101 node "fn" uses unknown icon "aws:lamda" {"node":"fn","icon":"aws:lamda"}
      fix: use icon "aws:lambda"
      fix: run `orrery icons search lamda`
error DG108 unknown key "lable" in node "db" {"where":"node \"db\"","key":"lable"}
      fix: rename "lable" to "label"
failed: 2 error(s), 0 warning(s)

仕様エラー（DG1xx）があるとレンダリングは停止します。構成上の警告（DG2xx：ノードを通るエッジ、ラベルの衝突、読みづらいほど幅の広い図）があっても、--strict を指定しない限り処理は続行されます。render --json はすべてのファイルをアトミックに書き込み、各出力のサイズと SHA-256 を記載した結果を出力します。

評価する前に測定するレビューボード

orrery review は、読者が目にする幅（README のカラム幅である 880 px）で図を確認し、6 つの観点を採点します。公式の規則、レイアウト、グリッド、矢印とフロー、重なり、サイズと品質です。

$ git show v0.2.1:skills/orrery/examples/gitops-kubernetes.yaml > gitops-0.2.yaml
$ orrery review gitops-0.2.yaml --width 880
review gitops-0.2: 1964x786 in a 880px column, seen at 880x352 (scale 0.45, light)
score 85.3/100  FAIL (pass = no blocker or major and score >= 85)
...
blocker quality.label-size node labels render at 5.82px at this width (1964px canvas shown at 0.45x)
        fix: use direction: down so the diagram is narrower

レビューループによってこの図のスコアは 98.5 となり、合格しました。現在は上から下へ流れる構成になり、README のカラム幅でもラベルが等倍で表示されます。

Claude Code では、/orrery:review <spec> を実行すると、レビューループ全体が動きます。コードで数えられるものはすべて測定します。重なり、交差、整列、ジグザグや避けられる折れ曲がり、アイコンのすぐそばをかすめる線、空またはいびつなグループ、表示幅での文字サイズとコントラストです。読み取り専用のエージェントは並列に実行され、数えられないものを評価します。

• conventions-reviewer は、AWS の資料、Azure Well-Architected、Google のアイコンガイド、C4 表記法から引用した、各ベンダー独自のルールを確認します。
• flow-reviewer は、矢印が伝えるストーリーを確認します。
• legibility-reviewer は、PNG を表示サイズで読みます。
• accuracy-reviewer は、該当する場合、図をコードや図示されたインフラストラクチャと照合します。

指摘が認められるのは、測定値、ベンダーのルール、またはソースの行を引用している場合に限られます。各ラウンドでは、patch-proposer エージェントが 2～4 個の修正候補セットを作成し、orrery patch がそれらをすべて一度に試します。最良の候補でスコアが上がり、かつ重大な計測値が悪化しなかった場合にのみ、そのラウンドの結果を採用します。ループは 3 ラウンド経過するか、改善のない状態が 2 ラウンド続くと停止します。ビジョンモデルは重なりや交差の数え上げが不得意なため、それらの判定を任せることはありません。評価基準は references/review にあり、同じチェックをサブエージェントなしでスキルがインストールされている場所から実行できます。

コードから図を描くエージェント

Claude Code では、/orrery:draw <what to draw> を実行すると、システムそのものを起点にします。planner エージェントはインフラストラクチャとコード（Terraform、CloudFormation、SAM、CDK の出力、Kubernetes、Compose、ハンドラー）を読み取り、すべてのサービス、境界、フローを、それぞれの出典となるファイルと行番号とともに返します。また、インフラストラクチャで宣言されているフローと、コードからのみ推測されるフローを区別し、何が省略されているか、その理由も示します。仕様が作成される前に、このリストを確認します。その後、仕様を作成して検証し、レビューボードにかけます。ここでは 4 人目のレビュアーである accuracy-reviewer が独自にソースと図を照合します。存在しないノード、トラフィックとして描かれた依存関係、逆向きの矢印、誤ったサブネット内のサービスなどを確認します。このエージェントにはプランナーの推論が共有されないため、その誤りを引き継ぐことはありません。

/orrery:doc <topic> は設計ドキュメントを作成します。プランナーが各観点（概要、リクエスト経路、データ、デプロイ、障害対応）につき図を 1 つ選び、diagram-author エージェントが並列に図を描き、それぞれをレビューしてから、orrery doc が Markdown を HTML または Word に変換し、図に番号を付けます。

修正は議論ではなく測定に基づきます。patch-proposer エージェントは、さまざまな方針（矢印を減らす、構成を変える、表現を改善する、ベンダーのルールに従う）で修正候補セットを作成します。orrery patch は各候補をそれぞれ独立したコピーで評価し、ほかの点を悪化させずに最高のスコアを得たものだけを採用します。プラグインのフックが、エージェントが仕様を書き込むたびにすぐ検証するため、レンダリング前に修正方法とともにエラーが返されます。計画と正確性に関するルールは planning.md と accuracy.md にあり、サブエージェントを利用できないクライアントでも同じチェックを順番に実行できます。

プルリクエストで

このリポジトリは GitHub Action としても機能します。すべての仕様を検証、レンダリング、レビューし、プルリクエストが変更した仕様の図を描き、スコアと画像へのリンクを記載したコメントをプルリクエストに 1 件だけ残します。

on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: Sagargupta16/[email protected]
        with:
          specs: docs/**/*.yaml   # git pathspec globs, one per line
          fail-on: error          # or warning, or review (fail when the review does not pass)

エディターとブラウザー

orrery lsp は仕様ファイル用の言語サーバーです。該当する文字位置に診断結果を表示し、修正候補をクイックフィックスとして提供し、アイコン ID、グループの種類と ID を補完します。editors/vscode はそのための軽量な VS Code クライアントであり、Language Server Protocol に対応するエディターなら、どれでも同じサーバーを利用できます。プレイグラウンド では CLI 独自のパーサー、レイアウト、レンダラー、レビューをブラウザー上で実行できます。仕様を編集して描画の更新を確認し、すべての形式をダウンロードしたり、仕様を含むリンクを共有したりできます。

コマンド

コマンド	説明
render <spec> [-o base] [-f svg,png,drawio,drawio.svg,tsx,html,mmd,sequence.svg|all] [--theme light|dark|both] [--skin classic|stage] [--animate packets|flow|relay|none] [--static] [--view <name>|all]	仕様を検証し、レイアウトを作成して描画します。--view を指定すると、仕様のビューを 1 つ、または各ビューを個別のファイルとしてすべて描画します。
watch <spec> [-o base] [-f svg,png] [--review]	仕様またはローカルアイコンが保存されるたびに再描画し、--review を指定すると毎回レビューのスコアを出力します。
validate <spec> [--strict] [--json]	仕様のエラーと構成上の警告を、それぞれ修正候補とともに表示します。
review <spec> [--width 880] [--theme light|dark] [--strict] [--json]	読者が見る幅で図を評価します。<base>.review.json と、その幅での PNG を出力します（PNG が大きい場合は、1568 px に収まるよう縮小した <base>.review.look.png も出力します）。
patch <spec> <candidates.json> [-o best.yaml] [--width 880]	複数の候補パッチセットを一度に試し、それぞれを個別のコピーでレビューします。コメントと書式をそのまま保ちながら、スコアが改善する最良のものを採用します。
doc <design.md> [-f html,md,docx]	設計ドキュメントを作成します。各 `` 行は番号付きの図になります（HTML ではインライン SVG、Markdown では隣接する画像ファイル、Word では画像）。
mcp [--port 8765]	コマンドを Model Context Protocol ツールとして、stdio 経由または 127.0.0.1 上の HTTP で提供します。
mcp install <client> [project|user] [--force], mcp install --list	ファイルのほかの部分を保持したまま、クライアントの MCP 設定に orrery サーバーのエントリーを書き込みます。
diff <before> <after> [-o changes.svg] [--json]	2 つの仕様の差分を表示します（git:<ref>:<path> は git から読み込みます）。ノード、グループ、エッジの追加、削除、名前変更、変更をテキスト、JSON、または変更箇所を色分けした新しい図で表示します。
verify <spec> [--link] [--commit <sha>] [--json]	すべての evidence: が実在するファイル、行、識別子を指しているか確認します。--link を指定すると、各ノードの url を特定のコミットに固定したパーマリンクに設定します。
describe <spec> [--json]	レイアウト済みの図について、グループ、ノード、その配置、接続関係をプレーンテキストで説明します。
lsp	stdio 経由でエディター向けの言語サーバーを起動します。
icons search <words> [--pack aws]	公式名付きで、関連度順にアイコン ID を表示します。
icons show <id>, icons list, icons packs	カタログとそのソースを参照します。
icons fetch	オフラインでの描画に備えて、ロゴとグリフのライブラリーをダウンロードしてキャッシュします。
icons new <name>, icons check <file.svg>, icons adopt <file.svg> --name <name>	24 グリッド上で独自のアイコンを描画します。両方のスキンとテーマでコンタクトシートを作成して描画ルールに照らして確認したり、誰かの SVG をクリーンな local: アイコンとして取り込んだりできます。
styles	すべてのグループの種類とノードの形状を表示します。
init [template]	サンプルの 1 つをもとに開始します。
import <mermaid|terraform|cloudformation|compose|kubernetes|sql|picture> <file> [-o diagram.yaml]	Mermaid のフローチャート、Terraform、CloudFormation または CDK のテンプレート、Compose ファイル、Kubernetes マニフェスト、SQL スキーマ（各ノードに evidence: を付与）から仕様を作成します。または、orrery が描画した SVG や PNG から仕様を読み戻します。
doctor, demo	インストールを確認し、すべてのサンプルを描画します。

アイコンパック

パック	アイコン数	ソース	同梱
aws	810	AWS Architecture Icons、2026-07-31 パッケージ	バンドル
azure	636	Azure Architecture Icons V24	バンドル
gcp	233	Google Cloud icons、Google の 2026 年 5 月のガイドに従ってコアアイコンとカテゴリ別アイコンを製品に対応付け	バンドル
k8s	40	Kubernetes community icons	バンドル
github	399	GitHub Octicons	npm @primer/octicons
ibm	2,776	IBM Carbon icons、IBM の図表ノードアイコンと製品グリフ	npm @iconify-json/carbon
logos	2,151	SVG Logos	npm @iconify-json/logos
si	3,351	Simple Icons	npm @iconify-json/simple-icons
tabler	6,286	Tabler Icons	npm @iconify-json/tabler
ph	1,527	Phosphor Icons、接尾辞で 6 種類のウェイトを指定（ph:handshake-duotone）	npm @iconify-json/ph

バンドル済みパックはベンダーからのダウンロードとしてのみ提供されるため、スキルに同梱され、オフラインで動作します。npm パックは、固定された SHA-256 と照合したうえで、レンダリング時にローカルの node_modules、ユーザーキャッシュ、または jsDelivr から読み込まれます。orrery icons fetch を実行すると事前にキャッシュでき、詳細は icons.md に記載されています。Renovate の月次依存関係 PR では、ベンダーのページで新しいリリースも確認し、更新されたパックを取り込みます。アイコン、ロゴ、商標は各所有者に帰属し、THIRD_PARTY_NOTICES.md に記載の条件に従って使用しています。AWS、Microsoft、Google の利用条件では、アーキテクチャ図での使用が認められています。

コミュニティ

orrery で図を作成しましたか？Show and tell で共有してください。質問は Q&A へ、アイコン、例、出力、スタイルのリクエストは Ideas へお寄せください。バグを見つけましたか？issue を作成してください。orrery によって図の作成がはかどった場合は、スターを付けると、ほかの人にも見つけてもらいやすくなります。

開発

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build                       # src/ -> skills/orrery/scripts/orrery.mjs
pnpm gallery                     # re-render examples/ and docs/
node scripts/check-repo.mjs      # dashes, links, counts, doc snippets, gallery freshness
pnpm sync-icons                  # rebuild icon catalogs (--latest re-pins new vendor releases)
node scripts/pack-npm.mjs        # stage the npm package in out/npm (a GitHub release publishes it)

各要素の仕組みについては CONTRIBUTING.md、問題の報告については SECURITY.md をご覧ください。

ライセンス

コードとドキュメント：MIT。アイコン、フォント、ベンダー提供のエンジンにはそれぞれ独自のライセンスが適用されます：THIRD_PARTY_NOTICES.md。