📘至高のウィンドウ切り替えを目指して『JINRAI(迅雷)』をつくった

[[📒Articles]] > [[📒2026 Articles]] ![[2026-03-01.webp|cover-picture]] [[macOS]]で理想のウィンドウ切り替えスクリプト『[[🦉JINRAI]]』をつくりました。 ## ウィンドウ切り替えのユースケースと課題パソコンで作業をしていると『ウィンドウ切り替え』を行う機会は多いでしょう。その手法も数多くあると思います。私の場合は主に以下3つのユースケースがあります。 ![[2026-03-01-12-00-46.avif]] ### 1. 直前にアクティブだったウィンドウをアクティブにしたいとき 2つのウィンドウを行き来しながら交互に作業したい場合です。たとえば[[Google Chrome]]で調べ物をしつつ、[[Obsidian]]でメモをとる場合など。そのようなときは[[AltTab]]を使ってきました。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://alt-tab-macos.netlify.app/public/favicon-32x32.png" /> <span class="link-card-v2-site-name">alt-tab-macos.netlify.app</span> </div> <div class="link-card-v2-title"> AltTab - Windows alt-tab on macOS </div> <div class="link-card-v2-content"> Windows alt-tab on macOS </div> <a href="https://alt-tab-macos.netlify.app/"></a> </div> しかし、[[AltTab]]には2つの課題がありました。 - **直前のウィンドウに移動しないときがある** - 再現条件不明 - 不定期に発生するので地味にストレス - **表示してほしくないウィンドウまで表示されてしまう** - 設定で緩和できるが[[Scoot]]などのアプリケーションでは効果がない - 閉じているつもりの待機アプリケーションも表示される - 設定で非表示にしているつもりだが、私のやり方が悪いのかも...... - [[📝AltTabで起動しているつもりのないアプリケーションが表示されてしまう]] ### 2. 視界にある別のウィンドウをアクティブにしたいとき目では認識している別のウィンドウをアクティブにしたいときは、トラックパッドや[[ポインティングスティック]]で移動することが多いです。大きな問題はありませんが、以下の理由から至高の方法とは言えないでしょう。 - **キーボードから一時的に手を離すことになる** - 距離は近いので大きな問題ではない - **マウスポインタの位置を見失っているときは、別のウィンドウへと速やかにマウスポインタを移動できない** 別の方法もありますが、いずれもツール起動後に判断が必要となるため効率的とは言えません。 - **[[AltTab]]で別のウィンドウを選んで移動する** - 別のウィンドウが何番目に表示されているかを **[[AltTab]]起動後に** 目視で確認し、必要なキータッチ数を決める必要がある - **[[Scoot]]で別のウィンドウが表示されている領域に移動する** - 別のウィンドウが表示されている領域のキーマップを **[[Scoot]]起動後に** 目視で確認し、キー入力する必要がある <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://github.githubassets.com/favicons/favicon.svg" /> <span class="link-card-v2-site-name">GitHub</span> </div> <div class="link-card-v2-title"> GitHub - mjrusso/scoot: Keyboard-driven MacOS cursor actuator </div> <div class="link-card-v2-content"> Keyboard-driven MacOS cursor actuator. Contribute to mjrusso/scoot development by creating an account on GitHub. </div> <img class="link-card-v2-image" src="https://repository-images.githubusercontent.com/360176893/2dd81e80-ab4a-11eb-847e-bd51bae42fdd" /> <a href="https://github.com/mjrusso/scoot"></a> </div> ### 3. 視界にない別のウィンドウをアクティブにしたいとき視界に入らない、または背面に存在して不可視のウィンドウをアクティブにしたいときは、[[ミッションコントロール]]ですべてのウィンドウプレビューを表示してから、トラックパッドや[[ポインティングスティック]]で移動することが多いです。こちらも大きな問題はありませんが、場合によってはかなり非効率な方法になります。 - **キーボードから一時的に手を離すことになる** - **距離は近いので大きな問題ではない** - **マウスポインタの位置を見失っているときは、別のウィンドウへと速やかにマウスポインタを移動できない** - **マウスポインタの位置が別のウィンドウのプレビューから離れているときは、マウスポインタの移動に時間がかかる** - [[AltTab]]を使うと解決できるが、判断回数を減らすならはじめから[[AltTab]]に統一すべき - その場合は[[AltTab]]特有の課題がつきまとう ### 課題と要件の整理 [[AltTab]]は3つのユースケースすべてのソリューションを提供する素晴らしいツールですが、**UIのフィードバックなしには再現性のある操作がしづらい**という点が残ります。一方で、マウスカーソルに頼る方法は効率の理論値が高いとは言えません。 ![[2026-03-01-12-07-02.avif]] これらの不満から、私が理想とするウィンドウ切り替えの要件をあぶり出してみました。 - **ツールを起動する前から** 希望する操作に必要なキー操作が確定的である - 操作がキーボードで完結する - 3つのウィンドウ切り替えユースケースに対して、**ユースケースごとに直感的に**操作できる具体的な機能要件などが他にもありますが、量が多くなってしまうので軸となる要件のみに留めました。 ## JINRAI(迅雷)を作成先ほどの要件をすべて満たす既存ツールはなさそうでしたので、[[Hammerspoon]]のスクリプトとして動くものを自分でつくりました。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://github.githubassets.com/favicons/favicon.svg" /> <span class="link-card-v2-site-name">GitHub</span> </div> <div class="link-card-v2-title"> GitHub - tadashi-aikawa/jinrai: A Hammerspoon script for switching and recognizing windows at the speed of thought ⚡ </div> <div class="link-card-v2-content"> A Hammerspoon script for switching and recognizing windows at the speed of thought ⚡ - tadashi-aikawa/jinrai </div> <img class="link-card-v2-image" src="https://opengraph.githubassets.com/28556a2cbb79f453f365c19b4747d6359acbfc045e77e81caeecfa64ac7ca5cc/tadashi-aikawa/jinrai" /> <a href="https://github.com/tadashi-aikawa/jinrai"></a> </div> ![[2026-03-01-12-17-57.avif]] インストール・セットアップ方法はREADMEをご覧ください。 > [!attention] > 前提として[[Hammerspoon]]のインストールが必要です。 > [!left-bubble] ![[colot-face.webp]] **[[コロット]]** > コーディングは『[[GitHub Copilot CLI]] x [[Claude Opus 4.6]]』で行っております。 ## 機能紹介主な機能は以下の3つです。特に **『Window Hints』** には力を入れています。 - 🔠 **[[Window Hints (JINRAI)|Window Hints]]** - アプリアイコン＋キーヒントによるウィンドウ切り替え - アプリ名の頭文字をキーヒントのプレフィックスに自動割り当て - 同一プレフィックスのウィンドウが複数ある場合は複数キー入力で絞り込み - 他のウィンドウに完全に隠れたウィンドウは画面下部にドック形式＋プレビュー付きで表示 - アクティブウィンドウをオーバーレイでハイライト表示 - 🔳 **[[Focus Border (JINRAI)|Focus Border]]** - フォーカスが移動したウィンドウの枠を一瞬だけハイライト表示 - ↩️ **[[Focus Back (JINRAI)|Focus Back]]** - ホットキーで直前にアクティブだったウィンドウに戻る画像で説明するのは難しいので、動画をご覧ください。 ![](https://youtu.be/clwLqNw0kXw) > [!attention] > 『Window Hints』のデフォルトホットキーは `Alt+f20` という見慣れないものになっています。これは私が[[karabiner.ts]]([[Karabiner-Elements]])を使って、`;<Space>` を `Alt+f20`に[[2キーバインド]] しているからです。 > > 設定の `window_hints.hotkey.modifiers` と `window_hints.hotkey.key` で変更できます。 > [!note] > 動画ではシングルモニタのデモをしていますが、モニタが複数ある場合はウィンドウが所属しているモニタに対してそれぞれ表示されます。 ## 効果をふりかえる ### 要件冒頭の要件を満たしているかをふりかえってみます。 - **ツールを起動する前から希望する操作に必要なキー操作が確定的である** - 😀 [[Window Hints (JINRAI)|Window Hints]] の起動 -> `アプリケーションの先頭文字` で大抵のケースは確定的 - **操作がキーボードで完結する** - 😆 [[Window Hints (JINRAI)|Window Hints]] と [[Focus Back (JINRAI)|Focus Back]] で必要な操作は網羅 - **3つのウィンドウ切り替えユースケースに対して、ユースケースごとに直感的に操作できる** - 😆 [[Window Hints (JINRAI)|Window Hints]] と [[Focus Back (JINRAI)|Focus Back]] で必要な操作は網羅私は`G`から始まるアプリケーションを使っていることが多いので、『キー操作が確定的』でないことも多いです。ただ、その場合も『残りの候補から選んで1キー押すだけ』で良いので些細な問題に過ぎません。 ![[2026-03-01-13-37-16.avif|frame]] *Gで始まるツールの2キー目として `ASF` の候補が表示される* ### 課題冒頭の課題から解決に直結したものを挙げてみます。 | 課題 | [[Window Hints (JINRAI) \| Window Hints]] | [[Focus Back (JINRAI) \| Focus Back]] | [[Focus Border (JINRAI) \| Focus Border]] | | ---------------------------- | ----------------------------------------- | ------------------------------------- | ----------------------------------------- | | **直前のウィンドウに移動しないときがある** | - | ✅ | - | | **表示してほしくないウィンドウまで表示されてしまう** | ✅ | - | - | | **キーボードから一時的に手を離すことになる** | ✅ | ✅ | - | | **[[AltTab]]起動後に目視が必要** | ✅<br> | ✅<br> | - | | **[[Scoot]]起動後に目視が必要** | ✅ | - | - | | **マウスポインタの位置を見失う** | ✅ | - | ✅ | [[Window Hints (JINRAI)|Window Hints]]と[[Focus Back (JINRAI)|Focus Back]]には `window_hints.behavior.centerCursor` と `focus_back.behavior.centerCursor` というオプションがあります。それを有効にすると『アクティブウィンドウを切り替えたあと、そのウィンドウの中央にマウスカーソルを移動』することができます。デフォルトでは無効(`false`)になっていますが、**マウスカーソルを見失わなくなり、目的のウィンドウでマウスを使った操作をスムーズに行えるようになる** ので、差し支えなければ有効にしてみてください。 ```lua hs.loadSpoon("Jinrai") spoon.Jinrai:setup({ window_hints = { behavior = { -- ここをtrueに centerCursor = true, }, }, focus_back = { behavior = { -- ここをtrueに centerCursor = true, }, }, }) ``` ## まとめ [[macOS]]でのウィンドウ切り替えにいくつか不満があったので、理想のウィンドウ切り替えを行うために作成した[[🦉JINRAI]]を紹介しました。まだ作成して数日しか経っていないので、1週間くらい使ってみて改善点が見つかるかもしれませんが、『UI/UX』にはこだわりをもって妥協せずにつくったつもりです。もともとは[[🦉Toki]]の内部スクリプトでしたが、公開して他の方にも使っていただけるクオリティに到達したと判断したので公開しました。[[🦉JINRAI]]の利用に伴い、[[AltTab]]と[[Scoot]]、[[JankyBorders]]はアンインストールしました。ウィンドウの切り替え操作にモヤモヤを抱えていた[[macOS]]ユーザーの方がいらっしゃいましたら、是非お試しいただければと思います。 ## 2026/03/02 追記記事執筆時から追加で以下の機能を実装しました。 ### アクティブウィンドウから8方向キーで選択上下左右と斜め4方向、計8方向の向きに存在するウィンドウをアクティブにする機能を追加しました。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png" /> <span class="link-card-v2-site-name">Minerva</span> </div> <div class="link-card-v2-title"> 📜2026-03-02 JINRAIでWindow Hints表示後にfocus_backや上下左右のウィンドウをアクティブにするキーマップ設定を追加 </div> <div class="link-card-v2-content">JINRAIのWindow Hints表示中にfocus_back共有履歴を用いた直前ウィンドウ復帰と8方向directionKeys移動を追加し、エッジ距離・重なり・前面順・完全遮蔽除外を考慮した直感的なウィンドウナビゲーションを実装した経緯と仕様を整理した記録である</div> <img class="link-card-v2-image" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/Notes/attachments/report-chappy.webp" /> <a data-href="📜2026-03-02 JINRAIでWindow Hints表示後にfocus_backや上下左右のウィンドウをアクティブにするキーマップ設定を追加" class="internal-link"></a> </div> %%[[📜2026-03-02 JINRAIでWindow Hints表示後にfocus_backや上下左右のウィンドウをアクティブにするキーマップ設定を追加]]%% キーマップ例です。 ```lua spoon.Jinrai:setup({ window_hints = { navigation = { directionKeys = { left = "h", down = "j", up = "k", right = "l", upLeft = "y", upRight = "u", downLeft = "b", downRight = "n", }, }, }, }) ``` ### ウィンドウやタイトルでヒントキーを固定する設定ウィンドウのID(bundleID)やタイトル([[glob]])が特定ケースの場合にヒントキーを固定表示できるようになりました。 `window_hints.hint.prefixOverrides` で設定できます。設定例です。 ```lua spoon.Jinrai:setup({ window_hints = { hint = { prefixOverrides = { { match = { bundleID = "md.obsidian", titleGlob = "*- minerva - Obsidian*" }, prefix = "M", }, { match = { bundleID = "md.obsidian" }, prefix = "O", }, { match = { bundleID = "com.google.Chrome" }, prefix = "GC", }, }, }, }, }) ``` 詳細の仕様はREADMEの `hint.prefixOverrides` セクションをご覧ください。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://github.githubassets.com/favicons/favicon.svg" /> <span class="link-card-v2-site-name">GitHub</span> </div> <div class="link-card-v2-title"> jinrai/README.ja.md at main · tadashi-aikawa/jinrai </div> <div class="link-card-v2-content"> A Hammerspoon script for switching and recognizing windows at the speed of thought ⚡ - tadashi-aikawa/jinrai </div> <img class="link-card-v2-image" src="https://opengraph.githubassets.com/2ad3e4c9fb78033b863c69b2805ca6f75c92f357ddeb550210372e75acc0b5c9/tadashi-aikawa/jinrai" /> <a href="https://github.com/tadashi-aikawa/jinrai/blob/main/README.ja.md#hintprefixoverrides"></a> </div> 開発の詳細は以下です。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png" /> <span class="link-card-v2-site-name">Minerva</span> </div> <div class="link-card-v2-title"> 📜2026-03-02 JINRAIでWindow HintsのappPrefixOverridesでキーマップが衝突したときの回避ロジック検討 </div> <div class="link-card-v2-content">appPrefixOverridesで2文字prefixと1文字キーが衝突し即確定した問題に対し、window_hintsで全ヒントキーを自動的にprefix-freeへ再割当し、短いキーをhintChars順で延長する実装とテストを計画した</div> <img class="link-card-v2-image" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/Notes/attachments/report-chappy.webp" /> <a data-href="📜2026-03-02 JINRAIでWindow HintsのappPrefixOverridesでキーマップが衝突したときの回避ロジック検討" class="internal-link"></a> </div> %%[[📜2026-03-02 JINRAIでWindow HintsのappPrefixOverridesでキーマップが衝突したときの回避ロジック検討]]%% ## FAQ (2026/03/03 追加) ### `navigation.directionKeys` で上下移動すると意図しないウィンドウに移動してしまう (2026/03/03) `navigation.cardinalOverlapTieThresholdPx` の値を調整することで、期待通りの動きに近づく可能性があります。環境と個人の直感によって最適値は変わると思うので、一概に何がいいとは言えません。 ```lua spoon.Jinrai:setup({ window_hints = { navigation = { -- デフォルトは720 cardinalOverlapTieThresholdPx = 960, }, }, }) ``` ### 異なるスペースのウィンドウが候補に表示されない (2026/03/14) [[Window Hints (JINRAI)|Window Hints]]で現在のスペース(ワークスペース)と異なるスペースを表示するには、`window_hints.behavior.includeOtherSpaces` を `true` にします。 ```lua spoon.Jinrai:setup({ window_hints = { behavior = { includeOtherSpaces = true, }, }, } ``` ### ウィンドウが多いと[[Window Hints (JINRAI)|Window Hints]]のプレビュー表示が遅くなる (2026/04/13) 背面ウィンドウが多いとプレビューの描画に時間がかかるためです。[[🦉JINRAI]]のv0.6.0以上であればプレビューは遅延描画されるため操作ブロックにはなりません。遅延描画がどうしても気になり、プレビュー表示をやめたい場合は`occlusion.preview.enabled` を無効化してください。 ```lua spoon.Jinrai:setup({ window_hints = { occlusion = { preview = { -- プレビューを無効化する enabled = false, }, }, dock = { -- 表示が下になりすぎるのでマージンを広げた方がいいかも bottomMargin = 96, }, }, }) ```