Heads-up

Heads-up

Claude Code がタスクを完了したときや、あなたの対応が必要なときに、Mac、Linux、Windows PC で音声通知します。キーボードから離れていても、いつ戻ればよいかが分かります。

「Koshからお知らせします。確認をお願いします。」

Heads-up は、Claude Code（および Codex）用のプラグインです。小規模なローカル MCP サーバー、エージェントがいつ知らせるべきかを学ぶスキル、そしてフックで構成されています。エージェントが notify_user という 1 つのツールを呼び出すと、コンピューターから短い音声が再生されます。20 種類の内蔵クリップ、または Claude が選択した声で話すオリジナルのメッセージを利用できます。音声は、コンピューター上で動作する無料の音声、またはご自身のキーを使った ElevenLabs や Sarvam によるものです。通話中、集中モードまたはおやすみモードのとき、自宅から離れているときは通知を控えます。また、キーボードから離れるまで待つこともできます。

できること

• 7種類の音声による20個のアラート（アメリカ英語、イギリス英語、オーストラリア英語、インド英語の男性・女性音声）、組み込みクリップ140個。これらの利用にAPIキーは不要です。
• キーなしで動作：インストール直後から、組み込みクリップ（「こんにちは。確認をお願いします。」）を再生します。プロジェクト名やClaude自身の言葉はオプトイン機能です。ローカル音声をダウンロードするか、独自のElevenLabsまたはSarvamのキーを追加すると利用できます。
• ローカル音声（無料、任意）：キーやアカウントなしでコンピューター上で音声を再生する音声モデルです。ダウンロード前に試聴できる2種類のサイズがあります。音声は12種類（アメリカ英語、イギリス英語、インド英語）で、1日の上限はありません。ローカル音声を参照してください。
• プロジェクト名（ローカル音声または独自のキー）：「Brand Bakery Hubからこんにちは。」各プロジェクトの名前は一度だけ録音され、その後キャッシュされます。
• どのチャットからの通知か：複数のセッションを開いている場合、Claudeアプリに表示されるチャット名（またはClaude Codeで設定した/renameのタイトル）を冒頭で読み上げます。「Koshからこんにちは。スレッド：Safariのエクスポートボタンを修正。確認をお願いします。」ローカル音声では常にこの機能を利用できます。有料音声では、Claude自身が書いた行に限り利用できます。
• Claude自身の言葉（ローカル音声または独自のキー）：固定の文言だけでは不十分な場合、Claudeが短いmessage（「移行は実行されましたが、2つのテーブルを確認する必要があります。」）を追加し、その場で読み上げます。行からコードやリンクが取り除かれ、長さに上限が設けられたうえでキャッシュされます。キーを使う場合は、1日の文字数予算にも加算されます。録音できない場合は、通常のアラートが再生されます。
• プロバイダーの任意の音声（独自のキー）：設定ページで、ElevenLabsアカウントの音声やSarvamの37種類の話者を追加できます。その音声のアラートは、初めて再生するときに録音するか、一括で録音できます。
• 独自の文言（ローカル音声または独自のキー）：設定ページで任意のアラートの文言を変更できます。変更した行だけが録音されます。
• 確認できる利用料金：プロバイダーごとの今日と今月の文字数、およびElevenLabsプランのクレジットカウンターを確認できます。
• Claude Codeフックによる自動アラート：権限の確認プロンプトや、2分を超えて実行されるターンを通知します。Claudeがツールの呼び出しを忘れた場合も通知されます。バックグラウンドセッション（claude -p、SDKワーカー）はアラートを発生させません。
• 初期設定は控えめ
  • 離席検知（デフォルトではオフ）：過去60秒以内にキーボードまたはマウスを使っている場合は、音を鳴らしません。複数のセッションを開いていると、別のセッションで入力中にこのセッションから通知が届くことが多いため、デフォルトではオフになっています。必要に応じて設定で有効にしてください。
  • 通話と集中モード：マイクまたはカメラの使用中、macOSの集中モードまたはデスクトップの「通知を邪魔しない」モードがオンの間は、音を鳴らしません。通知の読み上げ中にマイクまたはカメラがオンになった場合（音声入力や通話など）は、すぐに停止します。
  • 停止：headsup stopを実行するか、設定ページの「停止」ボタンを押すと、読み上げの途中でアラートを停止します（後続のアラートも破棄されます）。1回のキー操作で停止したい場合は、macOSのショートカット（またはデスクトップのキーボードショートカット）にheadsup stopを割り当ててください。
  • 場所：保存済みのネットワーク（自宅、オフィスなど）でのみ再生するよう設定できます。ルーターのハードウェアアドレスでネットワークを認識します。GPSは使用しません。
  • サイレント時間、アラート間の間隔、1時間あたりの上限を設定できます。
• 耳に優しい音量：コンピューターがミュートまたは小音量の場合、アラートの再生中だけ音量を上げ、その後元に戻します。AirPodsとヘッドフォンの音量は50％を超えず、スピーカーは90％を超えません。Heads-upが音声の出力先を判別できない場合は、ヘッドフォン用の上限を適用します。
• 設定ページ：http://127.0.0.1:4777（headsup）からアクセスできます。ローカルのみで利用できます。

必要条件

• Node.js 20以降とClaude Code（またはCodex）。macOS、Linux、Windows 10/11で動作します。
• 録音する場合はffmpegが必要です。ローカル音声または独自のキーを使うときに必要です（brew install ffmpeg、sudo apt install ffmpeg、winget install Gyan.FFmpeg）。
• 任意：ローカル音声（ディスク容量は約420 MB、小型モデルでは210 MB）、または新しい行を録音する場合のみ、ElevenLabsおよび／またはSarvamのAPIキー。

プラットフォーム

	macOS	Linux	Windows
サウンド	組み込み（afplay）	PipeWire または PulseAudio（pw-play、paplay）、それ以外は ffplay	組み込み
安全な音量	組み込み	pactl または wpctl	Windows ヘルパー
通話（マイク、カメラ）	Xcode Command Line Tools（swiftc）でビルドする通話検出機能	PipeWire（pw-dump）または pactl。カメラは /dev/video* から取得	Windows ヘルパー（Windows 独自のマイクとカメラのプライバシー記録を読み取ります）
フォーカス／おやすみモード	フォーカスモード（手動およびスケジュール設定）	GNOME、KDE Plasma、Xfce、dunst、SwayNC、mako	おやすみモード（Windows 10 ではフォーカスアシスト）
離席（アイドル状態）	組み込み	GNOME、または X11 では xprintidle	Windows ヘルパー
キー	Keychain	secret-tool 経由のキーリング（GNOME Keyring、KWallet）	Credential Manager（Windows ヘルパー経由）

headsup install はこれらをすべて確認し、不足しているものを表示します。Linux ではディストリビューション向けのインストールコマンド（apt、dnf、pacman、zypper）を出力します。ヘルパーのビルドは不要です。Windows では、Windows に付属する C# コンパイラー（.NET Framework 4）で小さなヘルパーをビルドするため、追加のダウンロードはありません。Heads-up が検出できないものは設定ページと headsup status に報告され、決して「通話中ではない」と扱われることはありません。

Linux と Windows のサポートは 1.7.0 で追加されました。Linux は GNOME のおやすみモードを有効にした PipeWire でテスト済みです。それ以外のデスクトップ環境はベストエフォートで対応しています。Windows はまだ初期段階で、実機ではまだ動作確認されていません。動作しない場合は、issue を作成してください。SSH 経由、コンテナー内、またはサウンドサーバーのないマシンでは、何もないところで音を再生する代わりに、理由を示して通知をスキップします。

インストール

Claude Code では、次の 1 ステップで完了します。

/plugin install heads-up --marketplace abhishek207/headsup-mcp

ターミナルから実行する場合は、システムに必要なヘルパーもビルドし、headsup コマンドを追加します。

npx headsup-mcp install      # add --dry-run to see the changes first

チェックアウトから実行する場合は、npm run setup でローカルコピーを使って同じ処理を行います。更新後に再実行しても安全です。次の処理を行います。

1. Node と ffmpeg を確認し、Linux ではサウンド、通話、キーリング関連のツールも確認します。
2. ヘルパーをデータフォルダーにビルドします。macOS では通話検出機能（swiftc が必要）、Windows では Windows ヘルパーをビルドします。Linux では不要です。
3. Heads-up マーケットプレイスを追加し、Claude Code にプラグインをインストールして、~/.claude/settings.json で notify_user ツールを許可します（バックアップは settings.json.heads-up-backup に保存されます）。許可ルールがない場合、各セッションの最初の通知は許可プロンプトへの応答待ちとなり、離席中に役立たなくなります。
4. 旧プラグイン設定（MCP エントリー、フック、CLAUDE.md セクション）が見つかった場合は削除し、通知が重複しないようにします。
5. Codex がインストールされている場合は Codex にもプラグインをインストールします。/hooks でフックを信頼してください（Heads-up の更新後、Codex は毎回確認を求めます。確認するまでは codex exec でフックが Failed と報告されます）。
6. headsup コマンドを ~/.local/bin に書き込みます（Windows では %USERPROFILE%\.local\bin\headsup.cmd。Claude Code 自体のインストーラーも同じフォルダーを使用します）。

headsup uninstall を実行すると、設定を保持したまま、これらをすべて削除できます。

プラグインの内容

部分	Claude Code	Codex
マニフェスト	.claude-plugin/plugin.json（MCP サーバーをインラインで記述）	.codex-plugin/plugin.json
MCP サーバー heads-up	server.mjs	.codex-plugin/mcp.json 経由の server.mjs
スキル	skills/heads-up/SKILL.md	同じ
フック	hooks/hooks.json：プロンプト、通知、停止	hooks/codex.json：プロンプト、許可リクエスト、停止
マーケットプレイス	.claude-plugin/marketplace.json	同じファイル（Codex が読み込みます）

npm run validate でマニフェストを確認してください。

その他の MCP クライアント

任意の MCP クライアントから、stdio 経由でサーバーを単独で実行できます。

npx -y headsup-mcp serve

これにより、クライアントで notify_user ツールを利用できるようになります。スキルとフックが含まれるのは Claude Code プラグインのみです。ヘルパーは npx headsup-mcp install でビルドします。

使い方

headsup              # open the settings page
headsup status       # what would happen right now
headsup test review  # play an alert now
headsup stop         # stop the alert that's speaking
headsup mute 30      # mute for 30 minutes; headsup unmute
headsup off          # master switch; headsup on
headsup say "The build is green."   # hear a line of your own (local voice or your key)
headsup usage        # characters sent to your voice providers
headsup local install   # download the free local voice (full, or: headsup local install small); headsup local remove

エージェント向けの指示

設定ページには、どんなときに通知するか、何を伝えるかをエージェントに指示する欄があります。たとえば、「最初に私に必要なことを伝え、そのあとタスク名を言ってください」や「5 分未満で終わったタスクは通知しないでください」などです。Heads-up はこのテキストを専用の設定に保存し、セッション開始時に MCP サーバーの指示と notify_user ツールの説明に含めて、すべてのエージェントに渡します。CLAUDE.md やスキルファイルには書き込まれないため、プラグインを更新しても消えることはありません。すでに開いているセッションには、再起動後に変更が反映されます。再生される音声は、引き続きスイッチ、通知を控える時間帯、音量上限で決まります。

ローカル音声

キーの料金を払わずに、プロジェクト名や Claude 自身の言葉を読み上げたい人向けの、コンピューター上で動作する無料の音声です。ダウンロードするまではオフになっています。設定ページの「ローカル音声」で、各モデルと 12 種類の音声のサンプルを再生し、好みのものをダウンロードしたあと、「音声」の「この Mac 上」（Linux では「このコンピューター上」、Windows では「この PC 上」）から、そのモデルの 12 種類の音声のいずれかを選びます。macOS（Apple silicon および Intel）、Linux（x64 および arm64）、Windows（x64。実機では未検証）で動作します。ターミナルからは、headsup local install（高音質）または headsup local install small を実行します。

モデル	音質	ダウンロードサイズ	ディスク上のサイズ	新しい行ごとの処理時間（M4 MacBook Air）
高音質（推奨）	明瞭で自然	約 360 MB	約 420 MB	約 4 秒、メモリ約 730 MB
小型	やや粗く、少し不自然。速度は約半分	約 140 MB	約 210 MB	約 7 秒、メモリ約 500 MB

• 概要： sherpa-onnx で実行する、8,200 万パラメーターのテキスト読み上げモデル Kokoro です。小型モデルは同じモデルを 8 ビット数値で保存したもので、音質がやや粗くなるのはそのためです。Heads-up は公式リリースからダウンロードし、各ファイルを固定されたチェックサムと照合して、データフォルダーに保存します。それ以外の場所には何もインストールされません。
• 一度に 1 つ： 切り替えると別のモデルがダウンロードされます（エンジンは保持されます）。新しいモデルの準備ができるまでは、現在のモデルが引き続き動作します。ローカル音声で録音済みの行は、新しいモデルで作り直されます。
• 費用： 1 行ごとの料金はかかりません。1 日あたりの予算も、新しいプロジェクト名の上限もありません。新しい行を録音するたびに、数秒間 CPU とメモリを使用したあと解放します。ダウンロード後、設定ページにコンピューター上での使用量が表示されます。通知の合間は読み込み状態にならず、すでに作成された行はキャッシュされ、すぐに再生されます。
• 速度と長さ： 「ローカル音声」の「読み上げ速度」で話す速さ（0.7×～1.5×）を、「最長の行」で 1 回の通知で Claude が話せる長さ（デフォルトは 1,000 文字、最大 2,000 文字）を設定できます。無料のため、何が起きたか、どのレビューや判断、入力が必要か、どんな選択肢があるかなど、必要なことをすべて話すよう Claude に指示しています。長い行は最初の文の準備ができると再生が始まり、残りは再生中に作成されます。有料音声では、Claude 自身の言葉に対して、より短い上限が個別に設定されています。
• 音声： アメリカ英語が 6 種類、イギリス英語が 4 種類、インド英語が 2 種類（英語を読み上げるヒンディー語音声）あります。ネイティブのインド英語音声を使うには、キーを使って Sarvam を利用してください。
• キーも引き続き利用可能： ローカル音声は、ElevenLabs や Sarvam と並ぶ選択肢の 1 つです。コンピューター上でモデルを実行したくない場合は、利用せず、キーを使ってください。
• headsup local remove を実行すると削除されます。キーがない場合、プロジェクト名と Claude 自身の言葉は再びオフになります。

API キー

ElevenLabs または Sarvam で新しい音声を録音する場合にのみ必要です。プロジェクト名、自分の言葉、追加した音声、Claude 自身の言葉が対象です。ローカル音声にはキーは必要ありません。設定ページでキーを追加すると、システムのキー保管庫（macOS Keychain、Linux のキーリング、Windows Credential Manager）に保存され、ファイルに書き込まれたり、再表示されたりすることはありません。ElevenLabs のキーは保存前に検証されます（無料）。また、「テスト」ボタンを押すと、そのキーを使って短い音声が再生されます。Heads-up は環境変数 ELEVENLABS_API_KEY / SARVAM_API_KEY と、elevenlabs-api-key / sarvam-api-key という名前の Keychain 項目も読み取ります。

キーを設定すると、Claude の発話は音声化のためにプロバイダーへ送信されます。そのため、コード、パス、シークレットを発話に含めないよう Claude に指示します。また、送信前に、紛れ込んだリンク、ファイルパス、メールアドレス、キーのような文字列を、Heads-up が「リンク」「ファイル」などに置き換えます。デフォルトでは、1 日あたりの上限（1,000 文字）が自動録音されるすべての内容に適用されます。設定ページから録音する内容には上限はありません。

データの保存場所

• プラグインフォルダー（Claude Code では ~/.claude/plugins/ に保存されます）：コードと組み込み音声。
• データフォルダー（または $HEADS_UP_HOME）：macOS では ~/Library/Application Support/heads-up、Linux では ~/.local/share/heads-up（設定されている場合は $XDG_DATA_HOME/heads-up）、Windows では %LOCALAPPDATA%\heads-up です。設定、アラートログ、フックの状態、録音（segments/、cache/clips/）、使用状況のログ（usage.json）、ダウンロードした場合はローカル音声（local/）が保存されます。

プライバシーとセキュリティ

• コンピューターの外部に送信されるもの： キーを追加するまでは何も送信されません。ローカル音声はコンピューター上で再生されます。ダウンロード時には npm と GitHub からファイルを 2 つ取得しますが、ユーザーに関する情報は送信されません。キーを設定した場合、録音対象のテキスト（プロジェクト名、自分の言葉、Claude の発話）だけが ElevenLabs または Sarvam に送信されます。また、ElevenLabs の音声一覧とプランの使用状況を取得するための無料 API 呼び出しも行います。分析、テレメトリー、その他のサーバーへの送信はありません。
• コンピューター上に保持されるもの： 通話、フォーカス、離席、位置情報の確認はすべてローカルで実行されます。マイクとカメラの確認では、デバイスが使用中かどうかをシステムに問い合わせるだけです（macOS、PipeWire、または Windows のプライバシー記録）。デバイスを開いたり、何かを録画したりすることはありません。位置情報として使用するのはルーターのハードウェアアドレスで、設定ファイルに保存されます。アラートログ（Claude の発話を含む）は上記のデータフォルダーに保存され、ユーザー本人だけが読み取れます。
• キー： システムのキー保管庫（または環境変数）に保存され、ファイル、ログ、設定ページには保存されません。headsup uninstall を実行しても、再インストールに備えてキーは保持され、キーを削除するコマンドが表示されます。
• 設定ページ： 127.0.0.1 のみで待ち受け、127.0.0.1 と localhost からのリクエストにのみ応答します（DNS リバインディングなし）。他のウェブサイトからのリクエストを拒否し、別のサイトにフレームとして埋め込まれることもありません。30 分間操作がないと停止します。
• 依存関係なし： 素の Node とシステム標準のツールを使用します。実行時に取得するのは、要求された場合に限り、固定バージョンの sherpa-onnx ビルドと Kokoro モデルからなるローカル音声のみです。どちらも使用前に SHA チェックサムで検証されます。
• セキュリティ上の問題を見つけた場合は、SECURITY.md をご覧ください。

トラブルシューティング

• データフォルダー内の hook.log には、フックの判断とその理由が1行ずつ記録されます。
• 設定ページの「最近のアラート」には、再生されたものもスキップされたものも含め、すべてのアラートとその理由が表示されます。
• 1つのプロセスですべてを無音にするには、HEADS_UP_DISABLED=1 を設定します（テストに便利です）。
• 「このマシンではサウンドを出力できません」と表示される場合、Heads-up がサウンドサーバーを検出できていません（SSH セッション、コンテナー、PipeWire または PulseAudio のない Linux マシンなど）。別の方法でサウンドが届く場合は、HEADS_UP_ASSUME_AUDIO=1 を設定してください。
• Linux：headsup status には、デスクトップ上で検出できない項目が表示されます（デスクトップによっては「応答不可」、KDE Wayland ではアイドル時間など）。その場合、該当するチェックは単にスキップされます。
• Codex は、セッションが対話型かどうかをフックに伝えないため、長時間の codex exec の実行が完了したときにも通知されます。Claude Code のバックグラウンド実行（claude -p、SDK）は無視されます。
• Codex のフルオート（「YOLO」）モードでは承認を求めないため、承認アラートは発生しません。

音声とクレジット

音声は ElevenLabs（elevenlabs.io）および Sarvam AI によって提供されています。

• 英語のクリップ：ElevenLabs の無料プランで作成した、ElevenLabs の音声 Brian、Sarah、George、Alice、Charlie。クレジット：elevenlabs.io。非営利目的でのみ使用できます。
• インド英語のクリップ：Sarvam Bulbul v3 の音声 Aditya と Priya。
• ローカル音声：hexgrad による Kokoro-82M（Apache-2.0）を、sherpa-onnx（Apache-2.0）で実行しています。発音には espeak-ng（GPL-3.0）を使用します。オンデマンドでダウンロードされ、このパッケージには同梱されていません。

ご自身のキーで録音した音声は、ご自身のアカウントおよびプロバイダーの利用規約に基づいて作成されます。

コントリビュート

ご利用いただき、フォークして、変更してください。外部からのプルリクエストは受け付けておらず、自動的にクローズされます。バグ報告はイシューとして歓迎します。CONTRIBUTING.md をご覧ください。

ライセンス

Copyright (C) 2026 Brand Bakery。

コードは GNU General Public License v3.0（GPL-3.0-only）のライセンスで提供されています。自由に使用、変更、共有できます。変更したバージョンを配布する場合は、GPL の下で提供し、ソースコードを公開する必要があります。voices/ に含まれるクリップはこのライセンスの対象外です。voices/NOTICE.md をご覧ください。

---

Brand Bakery が開発・保守しています。