omarchy-plugin

Omarchy プラグイン

バーウィジェットのアイデアをゼロからマーケットプレイス品質のプラグインに仕上げる方法です。表示されないウィジェットに丸一日を費やさないために。プロセスそのものが成果物です。まず HTML でプロトタイプを作り、すべての状態について合意を得てから、実装します。

フェーズ 1：調査（エージェント、読み取り専用、並行して実施）

1. マーケットプレイスを調査します。 https://plugins.omarchy.org/catalog.json が全カタログです（サイトの registry.json は 404 です。GitHub の registry.json にあるのはリポジトリ URL だけです）。ID、名前、説明を Grep します。アイデアがすでに存在しないことと、希望する ID が空いていることを確認します。最も近いプラグインを 3～5 個、シャロークローンして、それぞれがバーに何を表示するか、パネルに何を表示するか、どのようにポーリングするか、何を参考にできるかを書き留めます。
2. 参考実装を確認します。 references/quattro-facts.md を読んでから、同梱のパネル /usr/share/omarchy/shell/plugins/panels/（power、network、bluetooth、audio）と、共有コンポーネントのライブカタログである plugins/dev-gallery/GalleryPanel.qml を確認します。
3. データを試します。 実際の CLI を実行し（対応している場合は --json を指定）、ウィジェットに表示できるフィールドを貼り付けます。実在するデータだけを使って設計します。

フェーズ 2：QML を書く前に HTML でプロトタイプを作成

ユーザーは見た目を重視します。パネルについて言葉で説明しても何も伝わりません。レンダリングされたパネルがすべてです。エージェントを複数に分けず、ひとつの視点で、一度に作業します。

1. option-a/b/c.html と、横に並べて iframe で表示する index.html を使って、3 つの方向性を作成します。3 つとも同じデータを使います。各ページには、すべてのウィジェット状態を示すモックのバー、続いてパネル、ライト／ダークの切り替えを用意します。ユーザーのテーマを ~/.config/omarchy/themes/*/colors.toml から読み込み、デフォルトで適用します。等幅フォントのスタック（"JetBrainsMono Nerd Font", ui-monospace）と、references/design-language.md のパネル寸法を使います。
2. ヘッドレス Chromium でそれぞれのスクリーンショットを撮り、何かを見せる前に自分で PNG を確認します。
3. 小さな Python HTTP サーバーを固定ポートで起動し、webbrowser.open を使って配信します。ユーザーのブラウザーを開きます。どの案を推すか、その理由を簡潔に伝えます。
4. 方向性を決めたら、design-<x>-full.html を作成します。すべての状態（正常、実行中、失敗、古い／警告、未設定、設定）を、それぞれ個別のカードで示し、その下に「理由」を 1 段落で記載します。通知もインラインでモック表示します。すべての文字列に、次の手順を示す文を使います。このページについて合意を得ます。
5. その後で初めて仕様を書きます。

フェーズ 3：リポジトリを開始

テンプレートを用意する方法は 2 つあります。以前に自分で作ったプラグインがある場合は、2 つ目を使います。サービス／ウィジェットの分離、テスト、CI がすでに整っています。

1. 組み込みプラグインをテンプレートにします。 omarchy plugin clone omarchy.clock --edit を実行すると、同梱のプラグインが ~/.config/omarchy/plugins/omarchy.clock-copy/ にコピーされます（ID は omarchy plugin list --json で確認できます。omarchy.clock はバーウィジェットとパネルを備えた最小のプラグインで、omarchy.power は優れたステータスパネルです）。そのフォルダーを ~/src/<repo> に移動し、manifest.json の ID を変更して、git init を実行します。その後、正規の方法（以下を参照）で再インストールします。クローンは omarchy plugin remove を実行するまで設定フォルダーに残ります。
2. 自作プラグインをテンプレートにします。 最後に作ったプラグイン（例：github.com/steveclarke/omarchy-headroom）からスケルトンをコピーします。対象は manifest.json、BarWidget.qml、Service.qml、CollectorProcess.qml、TintedIcon.qml、Model.js、tests/、tools/、CI ワークフロー、LICENSE です。ドメイン固有のロジックは取り除き、基盤部分は残します。エージェント向け指示ファイルはコピーしないでください（正規の方法でインストールを参照）。

どちらの方法でも、gh repo create <user>/<repo> --public --source=. --push を実行し、続いて omarchy plugin add https://github.com/<user>/<repo> --enable と omarchy-restart-shell を実行します。それ以降は ~/src で編集し、コミットしてプッシュし、omarchy plugin update を実行します。

フェーズ 4：ビルド

順序が重要です。各ステップの最後に、ユーザーが確認できるスクリーンショットを撮影します。

1. マニフェストと、バーにグリフが表示される BarWidget.qml。最初の1時間で行います。 ルートまたはスロットの implicitWidth／implicitHeight は 0x0 にします。
2. テストを含む、純粋関数の Model.js：解析、状態マシン、相対時間、エラークラスのマッピング。ケースは references/testing.md から選びます。
3. ウォッチドッグ付きの Process ラッパーを備えた Service.qml シングルトン（Headroom の CollectorProcess.qml をコピー）。テストが実際のハードウェアやリポジトリに触れないよう、test/stub/ にスタブバイナリを置きます。
4. ファーストパーティのパーツのみ（PanelHero、PanelSectionHeader、PanelSeparator、CursorSurface、PanelActionButton）で正常状態の Panel.qml を作成します。grim のキャプチャとプロトタイプを並べて比較します。
5. それ以外のすべての状態は、デバッグ IPC（omarchy-shell <id> debugState failed）で強制的に表示し、キャプチャして比較します。
6. マニフェストの barWidget.schema を使って SettingsView.qml を作成し、shell.updateEntryInline で保存します。
7. 通知：イベントごとに1件ずつ notify-send -u critical -A key=Label で送信し、イベントのタイムスタンプで重複を排除します。
8. デザイン監査：読み取り専用エージェントを3〜4つ使い、それぞれに1つの観点を割り当てます（ファーストパーティとの比較、先入観のない確認と文言の一覧、フローと堅牢性）。一度のパスで反映し、すべての状態を再度キャプチャして、もう一度確認を依頼します。ユーザーが完了と言うまで続けます。 プレビュー：パネルの境界にぴったり合わせて切り抜き（magick ... -format "%[pixel:p{x,y}]" でエッジのピクセルをサンプル）、中立色で余白を追加し、4隅すべてを拡大します。
9. 提出前にセキュリティ確認を行います：omarchy-plugin-security スキルを実行し（grep 監査の後、プッシュ済みコミットに対してマーケットプレイススキャナーをローカルで実行）、検出事項をすべて修正します。レビューを1回受けるたびに1日かかり、プッシュのたびにレビュアーはツリー全体を再確認します。
10. preview.png（拡大表示ですべての端を確認し、仮の名前のみを使用）、続いて references/release.md のリリース手順（バージョン、CI の成功、注釈付きタグ、GitHub リリース）、その後 references/marketplace.md に従ってマーケットプレイスへの Issue を作成します。

ユーザーのマウスに触れずに検証する

omarchy-shell <id> open、omarchy-shell shell toggle <id> を実行し、その後 omarchy-shell shell debugBarGeometry から取得したパネルのジオメトリを使って grim -g を実行します。 hyprctl -j cursorpos でカーソル位置を保存して finally で復元した後、hyprctl eval 'hl.dispatch(hl.dsp.cursor.move({x=..,y=..}))' でホバーします。何が起きたかを確認するためにユーザーへクリックを頼んではいけません。

ウィジェットが読み込まれない場合

references/debugging.md を上から順に確認し（ファイル、スキーマ、検出、有効化、読み込み、ライフサイクル、IPC、プロセス、操作）、最初に失敗した層で止めます。マニフェストがまだ無効な状態で、QML の問題だと推測してはいけません。

正しい方法でインストールする

ソースは ~/src/<repo> に置きます。omarchy plugin add <git url> --enable は ~/.config/omarchy/plugins/<id>/ にクローンするため、そちらで編集してはいけません。マニフェスト、グリフ、IPC を変更したら、コミット、プッシュ、omarchy plugin update、omarchy-restart-shell の順に実行します。プラグインフォルダー内にシンボリックリンクを置いてはいけません。個人情報をリポジトリ、フィクスチャ、スクリーンショット、履歴に含めてはいけません。

プラグインリポジトリにエージェント向け指示ファイルを置いてはいけません。 ツリー内のどこにも AGENTS.md、CLAUDE.md、GEMINI.md、.claude/、.cursor/、SKILL.md などを置いてはいけません。omarchy plugin add はコーディングエージェントが自動検出するパスにリポジトリをコピーするため、マーケットプレイスの審査でブロックされます。コントリビューター向けの案内は docs/CONTRIBUTING.md に記載します。最初のコミットから github.com/steveclarke/omarchy-headroom の tools/check-agent-files を bin/check にコピーし、CI に組み込みます。

スクリーンショットはパネルの境界に沿って切り抜き、画面全体を撮影してはいけません。 パネル領域を撮影すると、その背後にあるウィンドウも写り込みます（この方法で、ターミナルのログが公開リポジトリの履歴に含まれてしまったことがあります）。

参考資料

• references/quattro-facts.md：調査に何時間もかかる、Quickshell／Quattro の自明でない仕様。
• references/design-language.md：形状、トークン、コンポーネントの用語、状態色のルール、文言のルール。
• references/testing.md：状態のケース、実行中のライフサイクル確認、証跡の記録。
• references/debugging.md：障害対応の手順と、読み取り専用のコマンド。
• references/release.md：バージョン、CI、注釈付きタグ、互換性の説明。
• references/marketplace.md：提出文、バリデーターの癖、レビューのラウンド。