iTerm通知プラグイン (iterm-notification)

Tool
iTerm通知プラグイン (iterm-notification)

iTerm通知プラグイン (iterm-notification)

macOS上のiTerm2ターミナルで、AIコーディングツール（OpenCodeやClaude Codeなど）の処理完了やユーザー確認をネイティブ通知として表示する軽量ユーティリティです。アプリケーションバンドルやビルド手順を必要とせず、シェルスクリプトとJavaScriptプラグインで動作します。通知はiTermアイコンで表示され、通知クリックで該当のiTermタブにフォーカスを移せるため、ワークフローの中断が少なくスムーズに再作業へ移行できます。（約300字）

https://github.com/wonjun3991/iterm-notification

概要

iterm-notificationは、iTerm2のOSC 9エスケープシーケンスを利用して、AIコーディングツールのイベント（タスク完了やユーザー入力の要請）をmacOSネイティブの通知として表示する軽量ツールです。アプリケーションバンドルやコンパイル不要で、シェルから直接デバイスへエスケープシーケンスを出力するだけで通知を発火します。通知はiTermアイコンで表示され、クリックすると対応するiTermタブにフォーカスが移るため、開発フローを中断せずに作業に戻れます。READMEやSETUP.mdで導入手順が用意されており、シンプルなフックとJSプラグインで既存のAIツールへ組み込みやすく設計されています。

GitHub

リポジトリの統計情報

  • スター数: 2
  • フォーク数: 0
  • ウォッチャー数: 2
  • コミット数: 5
  • ファイル数: 6
  • メインの言語: JavaScript

主な特徴

  • iTerm2のOSC 9エスケープシーケンスを使ったネイティブ通知表示（アプリ不要）
  • シェルスクリプトとJSプラグインのみで完結するシンプル構成
  • 通知のクリックで該当のiTermタブへフォーカス移動
  • AIコーディングツール（OpenCode、Claude Code）向けに設計されたフック機構

技術的なポイント

iterm-notificationの核はiTerm2がサポートするOSC 9（Operating System Command）エスケープシーケンスの利用です。具体的にはシェルから printf ‘\e]9;message\a’ > /dev/tty のような出力を行うことで、iTerm2に「通知を表示せよ」という信号を送ります。これによりネイティブの通知センター（通知のアイコンやアクション）でiTermアイコンが用いられ、Script Editorや外部アプリを経由することなく軽量に通知を扱えます。

構成は非常にシンプルで、ビルドやバンドルが不要な点が大きな利点です。シェルフック（hooksディレクトリ）に配置したスクリプトや、付属のJavaScriptプラグインをAIツール側の終了処理や問い合わせタイミングに組み込むだけで動作します。これにより、既存のCLIベースのAIツールへ最小の改修で通知機能を追加できます。

実装上の注意点としては、OSC 9はiTerm2固有のエスケープシーケンスであるため、macOS + iTerm2環境に依存します。また、/dev/ttyへ直接書き込むため、TTYが存在しないプロセス（非対話的なジョブやCI環境）では動作しない場合があります。tmuxやscreenなどのターミナルマルチプレクサを経由している場合、エスケープシーケンスが透過されるかどうかの確認が必要です。さらに、通知のクリックでタブへフォーカスを移す動作はiTerm2側の設定やバージョンによって挙動が異なる可能性があるため、SETUP.mdの手順に従って環境設定を確認することが推奨されます。

この設計により、追加のランタイムやデーモンを導入せずに、AIツールのユーザー体験を改善できる点が特徴です。開発者は軽量なフックを用いて、タスク完了や「確認してください」といったポイントでユーザーへ確実に通知を届けられます。

プロジェクトの構成

主要なファイルとディレクトリ：

  • .gitignore: file
  • Makefile: file
  • README.md: file
  • SETUP.md: file
  • hooks: dir

…他 1 ファイル

まとめ

iTerm2固有のOSC 9を用いることで、最小限の導入でネイティブ通知を実現する実用的なユーティリティです（約50字）。

リポジトリ情報：