hammerspoon

hammerspoon

ホストの範囲：mini/macOS。このスキルは joi/Linux では無効のままにしてください。共有ソースはリポジトリに残してもかまいません。ホスト間で有効化リンクを同期したり、ローカルホストに Hammerspoon がないという理由だけで SSH に切り替えたりしないでください。リモート操作には、セッションのホスト認可ポリシーが適用されます。

単発の操作には hs -q -c '<lua>' を 1 回呼び出します。ホットキー、ウォッチャー、メニューバーなど、継続的な動作には ~/.hammerspoon/ 内のモジュールを使用します。レシピについては、REFERENCE.md を参照してください。

準備状況

hs -q -c 'return "ok"' を実行すると、ok が出力される必要があります。そうでない場合：

• 終了コード 69／「can't access message port」→ Hammerspoon が起動していない（open -a Hammerspoon）か、hs.ipc が読み込まれていません → ~/.hammerspoon/init.lua に require("hs.ipc") があることを確認してください。pathwatcher が設定を自動再読み込みするので、約 2 秒待ってから再試行してください。
• hs バイナリが見つからない → Hammerspoon のコンソールで hs.ipc.cliInstall("/opt/homebrew") を実行するようユーザーに伝えてください。
• ウィンドウ／アプリの呼び出しが何もせず終了する → hs -c 'return hs.accessibilityState()' が true を返す必要があります。false の場合、ユーザーが「システム設定」→「プライバシーとセキュリティ」→「アクセシビリティ」で許可します。

単発モード

hs -q -c 'hs.application.launchOrFocus("Obsidian") return "ok"'
hs -q -t 15 -c '<anything touching AppleScript or many windows>'   # default IPC timeout is 4s; busy main loop can also cause one-off "receive timeout" — retry

• 最終値を return しないと、出力はありません。テーブルはアドレスとして出力されます — return hs.json.encode(tbl) を使用してください（hs.geometry の矩形には .table が必要です。NaN 値があると encode は何も言わずに nil を返すため、安全な代替手段は tostring() です）。
• シェル引数はシングルクォートで囲み、Lua 内ではダブルクォートを使用します。複数行の場合は、heredoc hs -q <<'EOF' ... EOF または hs -q /path/file.lua を使用します（パスは ~、./、または / で始まる必要があります）。
• 終了コード：65 = Lua エラー（メッセージは stderr に出力）、69 = Hammerspoon が起動していない／ipc が見つからない。
• 単発の呼び出しで作成した状態は保持されません。hs -c 経由で作成したタイマー、ウォッチャー、コールバックは呼び出し後に GC され、実行されません。後で実行または発火させる必要があるものは、永続モードで実装してください。
• 順序制御：フォーカスの変更やタブの読み込みなどの非同期状態は、1 つのチャンク内では確定しません。また、hs.timer.usleep は Hammerspoon 自体をブロックします。1 回の呼び出しで操作し、シェルで sleep してから、次の呼び出しで状態を読み取ってください。

永続モード

ホットキー／ウォッチャー／メニューバー項目には、~/.hammerspoon/<name>.lua を作成し、~/.hammerspoon/init.lua に require("<name>") を追加します。最初に ~/.hammerspoon/AGENTS.md を読んでください — プロジェクトの規約が記載されています。

• タイマー／ウォッチャー／メニューバーオブジェクトは、グローバル変数またはモジュールレベルの変数で参照を保持してください。そうしないと、GC によって何も通知されずに破棄されます。
• pathwatcher はファイルを保存するたびに設定を再読み込みします。ファイル全体を書き出してください（差分編集ではなく、Write を使用）。また、hs.reload() によって対話用のグローバル変数がすべて消去される点に注意してください。
• 保存後に確認してください：hs -q -c 'return "alive"'（再読み込みには約 1～2 秒かかります）。次に、hs -q -c 'return hs.console.getConsole()' | tail -20 で読み込みエラーがないか確認してください。

安全性

• 正常終了する :kill() を :kill9() より優先してください。未保存の作業が残っている可能性があるアプリを終了する前に、ユーザーに確認してください。
• モーダルダイアログ（hs.dialog）を開いたり、ほかのアプリでアラートを表示したりしないでください。イベント処理がブロックされます。
• hs.execute は Hammerspoon のメインループをブロックし（ホットキー／メニューバーがすべてフリーズします）、シェルコマンドを直接実行するか、モジュールから hs.task を使うことを優先してください。
• hs.eventtap.keyStrokes／クリックは、現在フォーカスされている対象に送られます。ユーザーが明確にそれを依頼した場合にのみ使用してください。