プラグイン（Plugins）

確認済み実機・内容確認: 2026-09-02 対象バージョン: v0.21.0 対象コミット: c5c9aa8d 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」パネルは 2 つのセクションでできている。上の Desktop plugins はデスクトップアプリの UI を拡張するデスクトッププラグインの一覧と管理、下の Agent plugins は Hermes バックエンドにインストールしたエージェントプラグイン（ツール・スキル・MCP サーバー・フック・スラッシュコマンド）の一覧とプロファイル別の有効 / 無効切替。ナビでは「ツールとキー」の下、「アーカイブ済みチャット」の上に位置する。

設定 > Plugins 画面

表示値は環境依存の例。

Desktop plugins セクション

デスクトッププラグインはスイッチでライブに有効 / 無効を切り替えられ、アプリの再起動は不要で、選択は再起動後も保持される。

同梱プラグイン

アプリのビルドには 3 つのデスクトッププラグインが同梱され、一覧に「bundled」Pill 付きで常に並ぶ（見出し右の件数は「3 installed」）。

名前	既定	内容
Accent Picker	オフ	ステータスバーに OKLCH カラーピッカーを出し、テーマのアクセントカラーをその場で差し替えて配色の再導出を試す作成者向けツール。色は保存されない
Bots	オン	Bot Mode。エージェントごとに 1 チャットのボット名簿、アバター、ルーティン、グループチャット、ボット間メッセージングを提供する。アプリに同梱され、不要ならここでオフにする。画面の詳細はボットを参照
Kanban	オフ	マルチエージェントのタスクボード。ボードページ、サイドバーのナビ行、ステータスバーの進行中件数を追加する

Bots をオフにするとメイン画面サイドバーの「BOTS」タブが消え、Kanban をオンにするとサイドバーにボードのナビ行が現れる。

画面の構成

画面表示（英語）	意味・動作
Desktop plugins	セクション見出し。右側に「`N` installed」（導入済み件数。同梱 3 件を含む）を表示
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 つも無いときの空状態表示

見出し下の説明文は「Bundled or dropped into the desktop-plugins folder. Disable to unload live.」（同梱、または desktop-plugins フォルダに置いたものが読み込まれる。無効化はライブでアンロードされる）。参考実装は別リポジトリ 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/<name>/plugin.tsx`。アプリ本体の Vite ビルドでコンパイルされる）。上記の 3 件

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

スイッチの切り替えはその場で反映される。有効化はプラグインの登録（activate）、無効化は登録解除（deactivate）をライブに行い、アプリの再読み込みは発生しない。
選択はローカルストレージ（キー hermes.desktop.pluginDecisions.v2）に永続化され、再起動後も保持される。端末ローカルの設定で、config.yaml には保存されない。
明示的に切り替えたことがないプラグインは、プラグイン自身の既定値 defaultEnabled（通常は有効。オプトイン設計のプラグインは無効のまま出荷できる）に従う。同梱の Accent Picker と Kanban は defaultEnabled: false、Bots は既定値を持たないため有効で出荷される。
無効化したプラグインも一覧には残り、スイッチでいつでも再有効化できる。
ゾーンにペインを出しているプラグインを無効化すると、ペインが消えて通知「プラグイン「（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 とフォルダ名の不一致など。

Agent plugins セクション

Hermes バックエンド側にインストールしたエージェントプラグインの一覧。説明文は「Plugins you installed into the Hermes backend — tools, skills, MCP servers, hooks, and slash commands. Portable ones are Agent Plugins packages (skills + MCP bundles that work in other agents too). Toggles apply to new sessions.」で、スイッチの切替は新しいセッションから反映される。

画面表示（英語）	意味・動作
Agent plugins	セクション見出し。右側に「`N` installed」
Applies to:	どのプロファイルのプラグインを一覧・切替するかを選ぶセレクタ。プロファイルが 2 つ以上あるときだけ表示される。既定プロファイルは「Hermes (default)」と表示。アプリ全体のプロファイルを切り替えずに別プロファイルのプラグインを管理でき、アプリ側でプロファイルを切り替えると選択は追随してリセットされる
Open plugins folder	バックエンドの `<hermes_home>/plugins` を開く。ローカル接続で、かつ「Applies to」で別プロファイルを選んでいないときだけ表示（リモートのバックエンドのフォルダは開けないため）
Search plugins…	名前・キー・説明の部分一致で絞り込む。一致なしは「No plugins match your search.」
No agent plugins installed yet.	何もインストールしていないときの空状態表示
Pill（user / git / project / pip / portable）	プラグインの由来（`source`）。並び順は user・git → project → pip の順、同じ由来の中は名前順。他のエージェントでも使えるパッケージには「portable」Pill が付く
スイッチ	有効 / 無効。失敗時は「Could not toggle <名前>」の通知

同梱（bundled）エージェントプラグインは一覧に出ない。リポジトリに同梱されている組み込みプラグインは既定で有効で、それぞれ専用の画面から設定するため、この一覧では source: bundled の行と dashboard_auth/ model-providers/ platforms/ で始まるキーの行を除外する（hermes plugins list --user と同じ選び方）。
キーを持たない行は読み取り専用。古いバックエンド（contract v6 より前）が返すキー無しの行はスイッチが無効になり、ツールチップ「Update the Hermes backend to manage this plugin from Desktop.」が出る。名前だけで切り替えると同名の別プラグインまで一緒に切り替わるおそれがあるため。バックエンドを更新すると操作できるようになる。
?tab=plugins&plugin=<id> のディープリンクで、該当行までスクロールしてハイライトされる（キーボードフォーカスも移る）。

ディープリンクからのインストール

hermes://plugin/install?repo=<owner>/<repo> 形式の URL（ドキュメントや配布ページの「Add to Hermes」系ボタン）を開くと、アプリ全体に「Install plugin」モーダルが表示される。設定画面の中ではなくグローバルに描画され、英語表示。インストール前に必ずユーザーの明示的な確認を求める。

画面表示（英語）	意味
Repository	対象リポジトリ。「Inspecting repository…」の間に中身を検査する
This package includes	パッケージに含まれる要素。「Agent plugin」（バックエンド側）と「Desktop UI」（デスクトッププラグイン）のそれぞれにチェックボックスがあり、入れるものを選ぶ。少なくとも 1 つ選ばないと「Select at least one component to install.」
Installs into the backend (~/.hermes/plugins/) / Installs into the connected backend	エージェントプラグインのインストール先。ローカルなら `~/.hermes/plugins/`、リモート接続中は接続先バックエンド
Installs into this app’s local desktop-plugins folder	デスクトッププラグインのインストール先（この端末の `desktop-plugins` フォルダ）
This URL uses an insecure or local scheme. …	`http://` やローカルスキームの URL への警告。本番用途は `https://` か `git@` を推奨
Before you install / Source code	信頼できる配布元だけからインストールするよう促す注意と、「View repository」「View plugin files」「Git clone URL」のソース確認リンク
Enable agent plugin after install	インストール後にエージェントプラグインを有効化する（チェックボックス）
Force reinstall (replace if already installed)	導入済みでも上書きして入れ直す
Install / Installing…	実行。成功すると「Agent plugin <名前> installed」「Desktop plugin <名前> installed」の通知
Missing env vars: … Add them in Settings → Keys.	プラグインが必要とする環境変数が足りない。ツールとキーで設定してから再実行する

前提: Hermes Desktop が起動していること。リモート接続中はエージェントプラグインが接続先バックエンドへ入る点に注意する。
失敗時: 「Agent plugin install failed」「Desktop plugin install failed」の通知が出る。「Plugin inspection is unavailable in this environment.」はバックエンドが検査に対応していない状態で、バックエンドを更新する。

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

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

安全上の注意

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