Shell プラグインアーキテクチャ

Omarchy デスクトップは omarchy-shell という単一の常駐 Quickshell プロセスとして動作しており、画面上に表示されるほぼすべてがその内部のプラグイン（Plugins）として構築されています。トップバーはプラグインです。そこからドロップダウンするコントロールパネル、絵文字ピッカーやクリップボードマネージャーなどのフルスクリーンオーバーレイ、Omarchy メニュー自体、ロック画面、Polkit 認証ダイアログ、さらにはバッテリーを監視したり夜間に画面を暖色化するヘッドレスサービスもすべてプラグインです。

これは単なる内部実装の話にとどまりません。デスクトップの特定の部分を無効化したり、別のものに置き換えたり、Omarchy のソースコードを 1 行も変更することなく自作のコンポーネントを開発できることを意味します。

公式のファーストパーティプラグインは Omarchy に同梱されており $OMARCHY_PATH/shell/plugins/ に配置されています。ユーザーが追加するプラグイン（自作の試作品や GitHub で見つけたもの）は ~/.config/omarchy/plugins/ に保存されます。どちらも起動時に同じ方法で自動検出されます。違いはディスク上の配置場所だけです。

インストール済みプラグインの一覧確認

omarchy plugin list

このコマンドは、検出されたすべてのプラグインの ID、有効/無効の状態、ファーストパーティ/サードパーティの別、プラグインの種類（kinds）、表示名を出力します。スクリプト等で処理する場合は --json を追加してください。

プラグイン ID は名前空間で管理されています。組み込みプラグインはすべて omarchy. から始まります（omarchy.clock、omarchy.network、omarchy.notifications など）。この名前空間は予約されているため、サードパーティプラグインが使用することはできません。

有効化と無効化

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

またはグラフィカルメニューを使用します：Setup > Plugins には Enable（有効化）、Disable（無効化）、Add（追加）、Clone（クローン）、Remove（削除）が用意されており、それぞれ適切な選択肢のみがスマートに表示されます。

有効化の状態は ~/.config/omarchy/shell.json に保存されます。サードパーティプラグインは、その ID がファイル内のいずれかの場所（バーのレイアウト設定、plugins[] 配列、または bar.id）に記載されている場合に有効とみなされます。バーウィジェット以外のファーストパーティプラグインはその逆で、デフォルトで有効になっており、disabledPlugins[] に明示的に記述された場合にのみ無効化されます。

完全なバープラグインには「無効」という状態はありません。システムには常に必ず 1 つのバーが必要なため、別のバープラグインを有効化することで置き換えます。バーウィジェットの配置方法は トップバー を参照してください。

Git からのプラグイン追加

サードパーティプラグインは、ルートディレクトリに manifest.json を持つ Git リポジトリです。

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

処理を実行する前に、プラグインは常駐 Shell プロセス内でサンドボックス化されていない任意のコードとして実行されることが明示され、URL が表示されて確認が求められます。これは非常に重要です。プラグインは静的な設定ファイルではなく、ユーザー権限でセッション中ずっと動作し続ける実行可能コードです。信頼できるリポジトリのみを追加し、有効化する前にコードを確認してください。

確認後、リポジトリがステージングディレクトリにクローンされ、マニフェストが検証されます。すでに同じ ID が使用されている場合はインストールが拒否され、問題がなければ ~/.config/omarchy/plugins/<id>/ に配置されます。--enable を付けない場合は今すぐ有効化するか尋ねられ、コードを先に確認したい場合は「いいえ」を選択できます。プラグイン内のコードが勝手に実行されたり、インストールフックが走ったり、sudo 権限を求められることはありません。ファイルのクローン、マニフェストの検証、IPC 経由でのフラグ切り替えのみを行います。

更新は同じリポジトリの fast-forward pull で行われます：

omarchy plugin update acme.weather
omarchy plugin update

ID を指定しない場合は、Git で管理されているすべてのプラグインを一括更新します。適用前に diff が表示され、ローカルの変更と競合する場合は更新が拒否され、新しいリビジョンが検証に失敗した場合は自動的にロールバックされます。

omarchy plugin remove acme.weather

削除を行うと、まずプラグインが無効化され、Git リポジトリの場合は削除され、シンボリックリンクの場合はリンクが解除されます。Git リポジトリのない手動作成のフォルダの場合は、誤削除を防ぐためタイムスタンプ付きのバックアップフォルダに移動されます。

組み込みプラグインのクローンと改変

これは最もおすすめのカスタマイズ機能です。組み込みウィジェットの動作を変更したい場合、$OMARCHY_PATH 配下のファイルを直接編集してはいけません（それらはパッケージに属しており、次回のアップデートで上書きされます）。代わりにクローンを作成します：

omarchy plugin clone omarchy.clock

これにより、プラグイン全体が ~/.config/omarchy/plugins/<username>.clock にコピーされ、名前が「My Clock」に変更されて自動的に有効化され、Shell の設定が組み込み版からあなたのクローン版へとシームレスに切り替わります（既存のバー位置や設定もそのまま引き継がれます）。--edit を追加すると新ディレクトリが $EDITOR で即座に開きます（メニューの Setup > Plugins > Clone Plugin も同様に動作します）。

ユーザー名をプレフィックスにすることで ID の重複を防ぎ、他者と共有しても衝突しません。元の omarchy.clock への呼び出しは自動的にあなたのクローンにルーティングされるため、既存の設定を変更する必要はありません。元に戻したい場合は omarchy plugin remove <username>.clock を実行するだけで、いつでも公式の組み込み版に復帰できます。

~/.config/omarchy/plugins/ 配下のファイルを保存すると、プラグインコードが自動的にホットリロードされるため、エディタを開いたままリアルタイムに変更結果を確認できます。

プラグインの自作開発

プラグインは manifest.json といくつかの QML ファイルを含むディレクトリです。マニフェストでは schemaVersion: 1、id、name、version、1 つ以上の kinds（プラグイン種別）、そして各種類の QML ファイルを指定する entryPoints オブジェクトを宣言します：

プラグインは複数の種別を同時に宣言できます（例えばメディアプラグインは service と bar-widget の両方です）。バーウィジェットには、表示名、カテゴリ、オプションの defaultSection、バーに複数配置可能かを指定する allowMultiple を含む barWidget 設定ブロックを追加します。

公開前に検証を実行できます：

omarchy plugin validate ./my-plugin

これは Shell が読み込み時に行うのと同じチェック（スキーマバージョン、必須フィールド、予約 ID の回避、安全で実在する相対エントリポイントパス、宣言したすべての種別に対するエントリポイントの存在、シンボリックリンクの不在など）を実行します。

詳細については Omarchy リポジトリの shell/README.md（マニフェストスキーマ、IPC 仕様、shell.json の構造）および shell/plugins/README.md（全ファーストパーティプラグインの ID、種別、エントリポイント一覧）を参照してください。

世界中への共有

素晴らしいプラグインが完成したら、公開 Git リポジトリにプッシュしてください。それが配布のすべてです。誰でもあなたのリポジトリ URL を指定して omarchy plugin add を実行するだけで、数秒で利用を開始できます。

多くの人に使ってもらうために、omarchyplugins.com に登録してください。これは Omarchy Shell プラグインのコミュニティディレクトリであり、作りたいウィジェットが既に存在しないか確認する最初の場所でもあります。開発を始める前にぜひ覗いてみてください！