Hyperキーを活用した便利ツールを作成しました（Hammerspoon）
はじめに
Hyperキー+任意キーのショートカットでアプリ切り替えやスクリプト実行できるHammerspoonプラグインを作成しました。 正確にはもともと個人利用のために作った簡易的なツールを、プラグインとして公開できるように拡張しました。 コード・設定はリポジトリで公開しています。
作成したモチベーション
アプリランチャーのような機能はRaycastなどで簡単に利用することができますが、以下の理由から自作することにしました。
- Hyperキーの扱い RaycastのHyperキーは4種の修飾キー（⌘+⌥+Ctrl+Shift）の組み合わせとして実現されており、他の修飾キーと組み合わせられない。独自キーとして扱えば、ショートカットの自由度が増す。
- 設定の同期 Raycastの自動同期は有料プラン限定。dotfilesで設定管理している身としては、手動のExport/Importは対応漏れのリスクがある。
これらに加え、Hammerspoonを試してみたかったこともあり、車輪の再発明かもしれませんが自作することにしました。
参考: https://evantravers.com/articles/2020/06/08/hammerspoon-a-better-better-hyper-key/
Hammerspoonとは
LuaスクリプトでMacを制御する強力な自動化ツールです。
有志が作成した機能がプラグインとして公開されています。
Hyperキーとは
Hyperキーとはかつてキーボードに存在した装飾キーで、今では失われたもののひとつです。（同様のものとしてFrontやTopといったキーも存在しました。）
現在では⌘+⌥+Ctrl+Shiftの同時押しを「Hyperキー」と呼ぶことがあります。他のショートカットと被りにくいため、独自のショートカットに利用されています。
ただし、この方法には前述の通り制約があります。本プラグインでは、F19キーを「真のHyperキー」として扱うことで、より柔軟なショートカットを実現しています。
Hyperキーを設定する（外部ツール）
このプラグインを使うには、まずHyperキーの設定が必要です。 Hyperキーはかつて修飾キーとして実装されていましたが、現在では修飾キーは7種類に限定されています。 macOSにおいてはUSB HID の 8bit modifierを受けているため、これ以上の拡張ができません。
参考: https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf
そのため修飾キーそのものとしての追加ではなく、通常のキーの中でHyperキーの扱いをするキーを用意する必要があります。 そこで一般的にHyperキーとして利用されるのがF19キーです。 F19はmacOSにおいてunusedとなっていて通常使われることはありません。 今回はこれを利用します。
2025年現在ではMacBookなどの多くのキーボードでF19キーは存在しません。
そこでF19の入力をソフトウェア的に解決する必要があります。
手段は問いませんが、私はデファクトスタンダードとなっているKarabiner-Elementsを使って caps lock をF19へと割り当てることにしました。
Karabiner-Elements 設定例
下記は最小限の caps_lock → f19 のルール例です。~/.config/karabiner/karabiner.json の "rules" 配列に追加してください。
{
"title": "Change caps_lock to f19",
"rules": [
{
"description": "CapsLock -> F19",
"manipulators": [
{
"type": "basic",
"from": { "key_code": "caps_lock" },
"to": [{ "key_code": "f19" }]
}
]
}
]
}
※ Hammerspoonでもキーのリマップは可能ですが、アプリケーションレベルのリマップであるHammerspoonに対して、カーネルレベルのリマップであるKarabinerｰElementsの方が信頼性があります。Hammerspoon開発者自身が「シンプルなリマップにはKarabiner-Elementsを使うべき」と明言していることからも、リマップは別のアプリケーションに委ねることとしました。
プラグインの機能詳細
今回は試しにアプリケーションランチャー機能とスクリプト実行機能（ShellScript, AppleScripts, Lua）を作りました。 またLuaのサンプルとしてウィンドウ移動機能を作成しました。 詳細はリポジトリを見ていただければと思うので概要だけ記載します。
アプリケーションランチャー機能
Hyperキーと別のキーとの組み合わせでアプリケーションが起動します。 アプリがすでに起動している場合はアクティブになり、すでにアクティブの場合は非表示になります。
スクリプト実行機能
ウィンドウ移動機能
画面分割によるアクティブウィンドウの移動機能をLuaスクリプトのサンプルとして用意しています。 サンプルとは言いつつ十分使いやすいものになっているかと思います。
私はアクティブウィンドウをJankyBordersで強調表示させており、強調のボーダーの幅の分だけウィンドウを少し小さく表示させたかったためギャップを設定できるようにしています。
その他スクリプト
実行したいスクリプトを簡単に呼び出す機能を簡易的に作成しました。
設定管理
これらの機能自体はプラグインにコードで実装されていますが、ショートカットはユーザが個別管理できるように設定ファイルから読み出すようにしています。
設定ファイルは ~/.hammerspoon/HyperkeyHub/config.json に配置します。
これによってプラグインはサブモジュールとしてインストール、設定はdotfilesで管理、といった運用が可能です。
なお、JSONを直接編集せずにGUIで設定することも可能です。
プラグイン設定例（config.json）
設定はJSON形式で管理します。下記は ~/.hammerspoon/HyperkeyHub/config.json のサンプルです。
{
"shortcuts": [
{ "key": "t", "action": { "type": "app", "bundleId": "com.apple.Terminal" } },
{ "key": "s", "action": { "type": "script", "path": "/path/to/scripts/sample.sh" } },
{ "key": "f", "action": { "type": "app", "bundleId": "com.apple.finder" } }
]
}
アプリ起動、シェルスクリプト実行などをキーに割り当てられます。詳細な設定項目はリポジトリのREADMEを参照してください。
おわりに
今回はHyperキーを活用した便利ツールの作成を行い、プラグインとして公開しました。 似たようなツールを使っている人も多いとは思いますが、気が向いたら使ってみていただけると幸いです。