# Omarchy Keyguide [English](README.md) · [한국어](README.ko.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Español](README.es.md) > 公開リポジトリ： ![Omarchy Keyguide の設定と HUD ライブプレビュー](preview.png) Omarchy Keyguide は、現在利用できるショートカットを入力を妨げない HUD に表示し、 安全な範囲でショートカットの登録・変更・削除を行える Omarchy 用プラグインです。 ## 目的と対象ユーザー Keyguide の目的は、Omarchy を使い始めたばかりの人が多数のキー操作を暗記しなく ても、現在のキー組み合わせで何ができるかをすぐ確認できるようにすることです。 慣れたユーザーにも、現在の PC で実際に有効なバインドやインストール済みアプリを 素早く検索する手段を提供します。 Keyguide では次のことができます。 - `Super` の修飾キー組み合わせを押したまま、現在使えるショートカットを確認 - 英語または選択中の表示言語で一般アクションを検索 - インストール済みのグラフィカルアプリとコマンドを同じ選択画面で検索 - 対応ショートカットを競合検査付きで移動・置換・削除・復元 - HUD の位置、倍率、透明度、テーマ連動、表示項目を調整 Keyguide はマクロレコーダーでも、無制限の Hyprland 設定エディターでも ありません。安全に再構築し、結果を検証できるアクションだけを変更対象にします。 ## 主な機能 - HUD の位置、倍率、透明度、テーマ連動、表示グループ、個別行の設定 - 英語（既定）、韓国語、日本語、簡体字中国語、スペイン語の設定画面と HUD - 空きキーは中央ポップアップで登録し、既存キーはその行の近くで変更または削除 - 一般アクション、インストール済みアプリ、コマンドを 1 つの検索欄から検索 - アプリのデスクトップアイコンを表示し、コマンドは `(CMD)` で識別 - 一般アクションを英語と選択中の言語の両方で検索 - 選択画面を開いている間にアプリの追加・削除を自動反映 - メニューに出ないバインドも含む Hyprland ランタイム全体での重複検査 - 競合、同時変更、リロードエラー時に変更前の状態へ正確にロールバック - Keyguide が移動した元のキーと新規作成したキーを「すべてリセット」で復元 ## 必要環境と互換性 対象環境は Omarchy `4.0.0-1`、Hyprland `0.56.2` 以降です。標準の Omarchy 環境に加えて Python 3、`xkbcli`、読み取り可能なキーボードイベント デバイスが必要です。ソースまたは Git プラグインから初めて導入する際は C コンパイラーも必要で、Arch Linux の `base-devel` で用意できます。 リポジトリのルートで次のコマンドを実行すると、現在の PC を確認できます。 ```sh PYTHONPATH=src/backend python -m keyguide_backend compat ``` 検出したバージョン、キーボードイベントデバイスの利用可否、エラー理由を JSON で表示し、未対応環境では 0 以外の終了コードを返します。 Linux は既定でキーボードとポインターのイベントデバイスを保護します。リポジトリを 複製またはプラグインを追加した後、リポジトリ内で入力アクセスを一度設定します。 ```sh sudo make install-input-access omarchy restart shell ``` これは systemd-logind の `uaccess` を使う udev ルールを 1 つ導入します。広範で 永続的な `input` グループへアカウントを追加せず、現在アクティブなローカルセッション だけにキーボード、マウス、タッチパッドのイベントアクセスを許可します。この ACL は Keyguide プロセスだけでなく、アクティブなセッションのユーザーアカウントに付与されるため、 有効な間は同じユーザーで動作する他のプロセスも対象のイベントノードを読み取れます。 解除する場合はリポジトリが残っているうちに `sudo make uninstall-input-access` を実行し、 Shell を再起動してください。 ## インストールと使い方 ### Omarchy Git プラグインとして導入 — 推奨 ```sh omarchy plugin add https://github.com/mrai125kr/omarchy-keyguide.git --enable ``` 初回有効化時には、リポジトリ内の C ソースから小さな非グラブ型入力オブザーバー をコンパイルするため、少し時間がかかる場合があります。外部から実行ファイルを ダウンロードすることはありません。トップバーに Keyguide アイコンが表示されたら、 クリックしてクイック設定または完全な設定画面を開けます。 ### 初めて使うとき 1. トップバーの Keyguide アイコンから完全な設定画面を開きます。 2. 表示言語を選びます。既定は英語で、韓国語、日本語、簡体字中国語、 スペイン語も利用できます。 3. HUD の位置、倍率、透明度、テーマ連動、表示する修飾キーグループを設定します。 4. `Super`、または `Super` と Ctrl・Shift・Alt の組み合わせを押したままにすると、 その組み合わせで現在利用できるショートカットが表示されます。 5. ショートカット編集で空きキーを選ぶと登録画面が中央に開きます。既存行の 「変更」ではその行の近くに編集画面が開き、「削除」ではそのキーが空きます。 6. 「すべてリセット」は復元可能な元のバインドを戻し、Keyguide が追加した ショートカットを削除します。無関係な Omarchy 設定はリセットしません。 ### アクションの検索と登録 1 つの検索欄から一般アクション、インストール済みアプリ、実行コマンドを探せます。 一般アクションは英語と選択中の表示言語の両方で検索できます。アプリには デスクトップアイコン、コマンドには `(CMD)` が表示され、任意引数の入力欄は コマンドを選んだ場合だけ表示されます。 既存アクションを別のキーに登録すると、重複を作らず現在のキーから新しいキーへ 移動します。使用中のキーを置き換える前には削除対象のアクション名を表示し、 もう一度確認します。安全に再構築できないアクションは理由付きの読み取り専用で 残ります。 ### 更新 ```sh omarchy plugin update mrai.keyguide --yes ``` Omarchy は差分を表示し、fast-forward で更新します。ローカル変更によって更新 できない場合は、その変更を先に保存または確認してください。 ### 削除 ```sh omarchy plugin remove mrai.keyguide ``` Git プラグインを削除すると、リポジトリ内で生成されたビルド結果も削除されます。 表示設定と独立管理されるショートカットモジュールは既定で残り、再インストールや 更新時に選択内容を保持します。 ### ソースからのインストールとアンインストール ```sh make test make install ``` 既存のインストールをユーザーの Shell 設定を保ったまま更新するには、次を使います。 ```sh PRESERVE_USER_SHELL=1 make install ``` 認証済みのインストール記録に含まれるファイルだけを削除するには、次を実行します。 ```sh make uninstall ``` Keyguide が管理するショートカットと表示設定もリセットしてから削除する場合は、 意図を明示します。 ```sh REMOVE_PREFERENCES=1 make uninstall ``` ## 安全性とプライバシー - 入力オブザーバーはキーをグラブ、消費、再送せず、入力内容を記録しません。 - Keyguide は `~/.config/hypr/bindings.lua` を変更しません。 - ユーザーがショートカット変更を確認した場合だけ、専用の生成モジュールを更新します。 - 保存前、Hyprland リロード後、実ランタイムで競合と結果の一致を確認します。 - エラー時は変更前の正確なファイルバイトへ戻し、部分設定を残しません。 - パスワード、API トークン、アカウント情報、ネットワークデータを収集・保存しません。 - アンインストーラーは認証済み記録外のファイルや独立したユーザー変更を削除しません。 ショートカット変更は `~/.local/state/omarchy/toggles/hypr/omarchy-keyguide.lua`、HUD 表示設定は `~/.local/share/omarchy-keyguide/settings.json` に保存されます。 ## トラブルシューティング - 最初に互換性確認コマンドを実行し、具体的なエラー理由を確認してください。 - コンパイラーがない場合は `omarchy pkg add base-devel` を実行してから、再度 インストールまたは更新します。 - HUD がキーの保持を検出できない場合は、互換性結果で読み取り可能なキーボード イベントデバイスがあるか確認します。 - インストール済みなのに UI が出ない場合は `omarchy restart shell` を実行します。 - ダウンロードしたソースは `omarchy plugin validate .` で構造を検証できます。 - 重複キー、曖昧なアクション、未対応キー、作業中の外部変更は保存せず、理由を 画面に表示します。 ## 開発と検証 ```sh make test make build ``` `make test` は非破壊の自動検証、`make build` は入力オブザーバーのビルドと Python バックエンドのコンパイル検査を行います。 GitHub Actions では `make test-ci` により、移植可能な C、Python、シェル構文、 安全性の検査を実行します。QML とプラグイン検証ハーネスには実際の Omarchy/Quickshell 環境が必要なため、リリース前には対応する Omarchy ホストで 完全な `make test` も実行する必要があります。 ## ライセンス MIT ライセンスです。詳細は [LICENSE](LICENSE) と [NOTICE](NOTICE) を参照して ください。