tmux 内で動かすターミナル常駐ツールのネイティブ通知は passthrough を有効化しないと届かない
開発環境
ツール設定
ターミナル
知識
運用
ターミナル常駐型の CLI/AI エージェントを tmux の中で起動すると、ホスト端末(iTerm2 / Kitty / Ghostty 等)のネイティブなデスクトップ通知やプログレスバーが出なくなることがある。設定は正しいのに通知だけ来ない、という症状で時間を溶かしやすい。
原因
これらの通知はターミナルのエスケープシーケンス(通知用 OSC 等)で実現されるが、tmux はデフォルトでパススルーを無効にしており、内側のアプリが出したシーケンスを外側の端末へ素通ししない。そのため内側ツールは通知を出しているつもりでもホスト端末に届かない。
対処
- tmux 設定で passthrough 許可(allow-passthrough を on)を有効化し、必要に応じて拡張キー機能(extended-keys と terminal-features の extkeys 相当)も合わせて有効化する。設定後は tmux の設定再読込が必要。
- ホスト端末側でも「エスケープシーケンス由来の通知を表示する」設定を別途有効にする必要がある(例: 通知センター連携を有効化し、escape sequence generated alerts の送出を許可)。両方そろって初めて通知が出る。
- パススルー対応はツール/端末のバージョンに依存するため、未対応の古い版では効かない点に注意する。
切り分け・検証
- OS の通知 API を直接叩くローカル通知デーモン方式(端末非依存で通知を出すヘルパー)は tmux を経由しないため動く。「ローカル通知は出るのに端末ネイティブ通知だけ出ない」なら tmux パススルーが原因の可能性が高い、という切り分けになる。
- 自分が tmux 内にいるかは環境変数 TERM_PROGRAM が tmux になっているかで判別できる。
- 設定反映後、通知が出るか・プログレス表示が外側端末に伝わるかで確認する。