プラグイン（Plugins）

確認済み実機・内容確認: 2026-07-22 対象バージョン: v0.19.0 対象コミット: 967e078a macOSWindows #hermes#settings#plugins

設定ナビの表示は日本語 UI でも英語の「Plugins」となる。i18n/ja.ts の settings.nav に plugins キーが無く、パネル内のラベル（settings.plugins ブロック）も未翻訳のため、英語（en.ts）へフォールバックして表示される（ロケールは define-locale.ts で英語辞書に深いマージをするため、欠けたキーは英語になる）。日本語 UI 内でこの画面に言及する唯一の文字列は、ゾーンのペインを持つプラグインを無効化したときの通知「設定 → プラグインで再有効化するとペインが戻ります。」（ja.ts の zones.pluginDisabledBody）である。

「Plugins」パネルは、デスクトップアプリの UI を拡張するデスクトッププラグインの一覧と管理画面。ナビでは「ツールとキー」の下、「アーカイブ済みチャット」の上に位置する。プラグインごとにスイッチでライブに有効 / 無効を切り替えられ、アプリの再起動は不要で、選択は再起動後も保持される。

画面の構成

画面表示（英語）	意味・動作
Desktop plugins	パネル見出し。右側に「`N` installed」（導入済み件数）を表示
Open plugins folder	`$HERMES_HOME/desktop-plugins` を OS のファイルマネージャーで開く。開けない場合はエラートースト「Could not open the plugins folder」
Rescan	ディスク上のプラグインフォルダを再スキャンする。コマンドパレット（Cmd+K）の「Reload desktop plugins」と同じ処理
Reveal in file manager	各行のフォルダアイコン。プラグインの `plugin.js` をファイルマネージャーで表示する（macOS では Finder）。ファイル実体を持つプラグインにのみ表示
Enable / Disable	各行右端のスイッチ（アクセシビリティ用ラベル）。ライブ有効 / 無効化
failed	読み込みに失敗したプラグインに付く Pill。行の説明欄に赤字でエラーメッセージを表示
No desktop plugins installed yet.	プラグインが 1 つも無いときの空状態表示

見出し下の説明文（blurb）は「ビルドに同梱されたもの、または desktop-plugins フォルダに置かれたもの（Hermes 自身が書いたものを含む）が読み込まれる UI 拡張。無効化はライブでアンロードされ、再起動後も保持される」という趣旨の英文が表示される。

コアツリーに同梱出荷されるデスクトッププラグインは現時点では無く（公式ドキュメントに明記。参考実装は別リポジトリ hermes-example-plugins）、プラグインを導入していない環境では空状態表示になる。

プラグインの種別（Pill 表示）

各行のプラグイン名の横に、由来を示す Pill が付く。一覧はディスク → ランタイム → 同梱の順、同種別内は名前順に並ぶ。

Pill 表示	内部種別	由来
on disk	`disk`	`$HERMES_HOME/desktop-plugins/<id>/plugin.js` に置かれたプラグイン。ユーザーが手で置いたものと、エージェント（Hermes）が書いたものの両方を含む
runtime	`runtime`	ランタイム読み込みパイプラインで種別 `runtime` を明示して注入されたプラグイン向けの種別（下の注記を参照）
bundled	`bundled`	アプリのビルドに同梱されたプラグイン（`apps/desktop/src/plugins/`。アプリ本体の Vite ビルドでコンパイルされる）

スイッチによるライブ有効・無効化

スイッチの切り替えはその場で反映される。有効化はプラグインの登録（activate）、無効化は登録解除（deactivate）をライブに行い、アプリの再読み込みは発生しない。
選択はローカルストレージ（キー hermes.desktop.pluginDecisions.v2）に永続化され、再起動後も保持される。端末ローカルの設定で、config.yaml には保存されない。
明示的に切り替えたことがないプラグインは、プラグイン自身の既定値 defaultEnabled（通常は有効。オプトイン設計のプラグインは無効のまま出荷できる）に従う。
無効化したプラグインも一覧には残り、スイッチでいつでも再有効化できる。
ゾーンにペインを出しているプラグインを無効化すると、ペインが消えて通知「プラグイン「（ID）」を無効化しました ─ 設定 → プラグインで再有効化するとペインが戻ります。」が表示される。

エラー表示

plugin.js の読み込み・登録に失敗したプラグインは、名前の横に「failed」Pill が付き、行の説明欄に赤字でエラーメッセージが表示される。読み込み失敗時にはトースト（「Plugin “（名前）” failed to load」）も出る。壊れたプラグインはエラー境界で分離されるため、アプリ本体は落ちない。ファイルを修正して保存すればホットリロードで復帰する。

プラグインの実体と追加手順

プラグインの実体は $HERMES_HOME/desktop-plugins/<id>/plugin.js の単一 ESM ファイル（既定では ~/.hermes/desktop-plugins/、名前付きプロファイル使用時は ~/.hermes/profiles/<名前>/desktop-plugins/）。フォルダ名はプラグインの id と一致させる。import できるのは @hermes/plugin-sdk・react・react/jsx-runtime の 3 つだけで、リポジトリのクローンやビルド手順は不要。書き方の全容は公式の Desktop Plugin SDK ドキュメント（developer-guide/desktop-plugin-sdk.md）にある。

前提: Hermes Desktop が起動していること。
操作: 「Open plugins folder」でプラグインフォルダを開き、<id>/plugin.js の形でファイルを置く。
期待結果: アプリがフォルダを自動検出して数秒以内に読み込む（ウィンドウ表示中は 5 秒間隔でフォルダをポーリング）。以後は plugin.js を保存するたびにホットリロードされ、再起動は不要。一覧に「on disk」Pill 付きの行が現れる。
失敗時の確認先: 一覧に現れないときは「Rescan」（またはコマンドパレットの「Reload desktop plugins」）を実行する。「failed」Pill が付いたときは行の赤字エラーメッセージを読む。よくある原因は、ディスクプラグインで JSX 構文を使っている（未コンパイルで読み込まれるため jsx() / jsxs() を使う）、上記 3 つ以外の import、default エクスポートの id とフォルダ名の不一致など。

Web ダッシュボードのプラグインとは別物

公式ドキュメントも明記しているとおり、このパネルが管理するのはネイティブデスクトップアプリ（hermes desktop）のプラグインだけである。Web ダッシュボード（hermes dashboard）には manifest.json を使う別系統のプラグインシステム（公式ドキュメント「Extending the Dashboard」）があり、Python の CLI / ゲートウェイプラグインもさらに別系統になる。フロントエンドのプラグインシステムとしては 3 つとも独立しており、コードも配布方法も共有しない（ただしデスクトップとダッシュボードは、バックエンドの plugin_api.py 名前空間 /api/plugins/<id> のみを共有する。プラグインにサーバー側処理を持たせる場合はこの共有マウントを再利用する ─ 公式ドキュメントに明記）。ダッシュボード側の画面についてはスキルとツールを参照。

安全上の注意

なお、このパネルのスイッチはレンダラ側（UI）の有効化であり、プラグイン付属の Python バックエンド（plugin_api.py）はこのスイッチでは読み込まれない。Python 側は config.yaml の plugins.enabled 許可リストで別管理される（公式ドキュメントが安全境界として明記）。