aerospace-macos-setup

AeroSpace macOS のセットアップ

基本的なワークフロー

macOS で AeroSpace を実際にセットアップしたり、問題をデバッグしたりする際は、このスキルを使用してください。ドキュメントや記憶に頼って推測するのではなく、インストール済みの aerospace CLI で直接確認してください。

1. インストールと実行状態を確認します：

command -v brew
brew list --cask nikitabobko/tap/aerospace
aerospace --version

aerospace --version に AeroSpace.app server version: Unknown と表示される場合、現在のコマンド実行環境からアプリサーバーに接続できていません。AeroSpace が停止していると判断する前に、サンドボックスの外で昇格権限を使って同じコマンドを実行してみてください。

2. AeroSpace を起動します：

open -a AeroSpace
open -b bobko.aerospace

アプリ名での起動に問題があるように見える場合は、バンドル ID 形式を使用してください。

3. アプリが起動してすぐに終了する場合は、アクセシビリティを確認します：

open 'x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility'

ユーザーが /Applications/AeroSpace.app を手動で有効にする必要があります。この問題が発生した場合、ログには通常 TCCAccessRequest for kTCCServiceAccessibility が表示されます。

4. アクティブな設定ファイルのパスを確認します：

aerospace config --config-path

~/.aerospace.toml がアクティブだと決めつけないでください。aerospace reload-config が成功するまでは、AeroSpace が /Applications/AeroSpace.app/Contents/Resources/default-config.toml を使って実行されている場合があります。

5. アクティブなキーバインドを確認します：

aerospace config --get mode.main.binding --json

想定したキーバインドが見つからない場合は、設定を再読み込みします：

aerospace reload-config

ユーザー設定

ユーザー設定が存在しない場合は、同梱のデフォルト設定から作成します：

cp /Applications/AeroSpace.app/Contents/Resources/default-config.toml ~/.aerospace.toml

~/.aerospace.toml の通常は [mode.main.binding] 以下を編集します。手動で編集する場合は apply_patch を使用してください。

アプリ／ワークスペース全体をモニター間で移動するには、ウィンドウの移動よりもワークスペースの移動を優先してください：

ctrl-alt-shift-up = 'move-workspace-to-monitor --wrap-around up'
ctrl-alt-shift-down = 'move-workspace-to-monitor --wrap-around down'

モニターが横方向に配置されている場合：

ctrl-alt-shift-left = 'move-workspace-to-monitor --wrap-around left'
ctrl-alt-shift-right = 'move-workspace-to-monitor --wrap-around right'

ユーザーが、単一のウィンドウを移動先モニターで現在表示されているワークスペースに移したいと明示した場合に限り、move-node-to-monitor を使用してください。移動先のワークスペースにすでに別のウィンドウがある場合、移動したウィンドウは半分／3 分の 1 などのサイズでタイル表示されます。「このアプリをもう一方の画面に移して、フルサイズのままにしたい」と考えるユーザーには、move-workspace-to-monitor の方が意図に合っています。

グローバルキーバインドには alt-shift-left/right/up/down を避けてください。macOS やテキストアプリでは、テキストの選択や特殊文字の入力に Option + Shift + Arrow をよく使うため、Google Docs でテキストが選択されたり、ターミナルに予期しない文字が入力されたりすることがあります。 ターミナルのタブ切り替えがおかしくなる場合は、ctrl-alt-up/down も避けてください。ターミナルやアプリのショートカット処理と、明示性の低いグローバルキーバインドが競合することがあります。

自動テスト

まず AeroSpace 独自のテスト方法を優先してください：

aerospace trigger-binding --mode main ctrl-alt-shift-down
aerospace trigger-binding --mode main ctrl-alt-shift-up

続いて、実行前後の状態を確認します：

aerospace list-monitors
aerospace list-monitors --focused
aerospace list-windows --focused --format '%{window-id} | %{app-name} | %{window-title} | %{monitor-id}'

この方法では、macOS に物理キー入力を送らせることなく、設定済みのキーバインドをテストできます。trigger-binding の実行後に OS レベルのホットキーが横取りされる問題を特にデバッグする場合に限り、実際のキー入力を合成してください。

キーバインドを使わずにコマンドを直接テストする場合：

aerospace move-workspace-to-monitor --wrap-around down
aerospace move-workspace-to-monitor --wrap-around up

アプリランチャーのホットキー

単純なアプリ起動／フォーカス用ショートカットには、AeroSpace の exec-and-forget を使用してください。open -a は既存のアプリインスタンスをアクティブにするか、アプリが起動していない場合は起動します。

よく使うアプリには、片手で無理なく操作できるキーバインドを優先し、未使用の AeroSpace ワークスペース文字を割り当て直してください：

alt-g = 'exec-and-forget open -a Ghostty'
alt-c = 'exec-and-forget open -a "Google Chrome"'

安全性は高いものの、人間工学的には劣るキーバインドの場合：

ctrl-alt-cmd-g = 'exec-and-forget open -a Ghostty'
ctrl-alt-cmd-c = 'exec-and-forget open -a "Google Chrome"'

ランチャーには cmd-c と cmd-g を使わないでください。cmd-c はコピー、cmd-g は通常「次を検索」に割り当てられています。ユーザーが C と G の AeroSpace ワークスペース用キーバインドを手放してもよい場合に限り、alt-c と alt-g を使用できます。

物理キーを押さずにランチャーのキーバインドをテストします：

aerospace trigger-binding --mode main ctrl-alt-cmd-g
aerospace trigger-binding --mode main ctrl-alt-cmd-c
aerospace trigger-binding --mode main alt-g
aerospace trigger-binding --mode main alt-c

Ghostty のネイティブタブ

Ghostty のネイティブ macOS タブを、1 つの実際の AeroSpace ウィンドウのように動作させようと、何度も時間を費やさないでください。Ghostty のネイティブタブは macOS のウィンドウマネージャー API では個別のウィンドウとして公開されるため、AeroSpace は「新しいタブ」と「新しいウィンドウ」を確実に区別できません。

詳しい失敗の経緯、一部の回避策、既知の誤った修正については、references/ghostty-native-tabs-aerospace.md をお読みください。

安定した推奨策：AeroSpace では Ghostty のネイティブタブを使わないでください。代わりに、AeroSpace のワークスペースやウィンドウを分ける、Ghostty の分割機能を使う、または 1 つの Ghostty OS ウィンドウ内で tmux などのターミナルマルチプレクサーを使ってください。tmux への移行手順については、references/tmux-in-ghostty.md をお読みください。

デバッグチェックリスト

• サンドボックス化された CLI の呼び出しで接続できない場合は、サンドボックスの外で aerospace --version を実行します。
• AeroSpace が実行中であることを確認するには、サンドボックスの外で ps -ax を実行します。
• 起動やアクセシビリティの動作が不明な場合は、最近のログを確認します。

/usr/bin/log show --last 10m --predicate 'process == "AeroSpace" OR eventMessage CONTAINS "AeroSpace"'

• 設定を作成または再読み込みするたびに、aerospace config --config-path を確認します。
• アクティブなサーバーがバインディングを認識していることを確認するには、aerospace config --get mode.main.binding --json を確認します。
• trigger-binding --mode main <binding> を使い、実行前後のフォーカスされたウィンドウの monitor-id を比較します。
• ショートカットを押すと文字が入力されたりテキストが選択されたりするとユーザーが伝えた場合は、AeroSpace のウィンドウ移動のデバッグを続けるのではなく、別のバインディングを選びます。
• ターミナルやブラウザーのタブ切り替えが機能しない場合は、alt-tab や alt-shift-tab などのタブベースの AeroSpace のデフォルトバインディングを削除します。
• フォーカスやタブの切り替えでポインターがモニター間を移動するように感じる場合は、on-focused-monitor-changed = [] を設定します。
• ターミナルのタブをクリックするとモニターが切り替わるように見える場合は、aerospace list-windows --all を使ってすべてのターミナルウィンドウを調べます。アプリ内ですでにウィンドウやタブがモニター間に分散している可能性があります。

ヘルパースクリプト

診断情報を簡潔にまとめて取得するには、scripts/aerospace_diagnose.sh を使います。ソケットへのアクセスやプロセス一覧の取得がブロックされる場合は、サンドボックスの外で実行します。

/Users/zakirov/.codex/skills/aerospace-macos-setup/scripts/aerospace_diagnose.sh