hey claudeとは｜Macで音声起動するClaude Codeの設定と使い方

hey claudeとは — Claude Codeを声で起動するツール

hey-claudeは、macOSで「Hey Claude」という呼びかけを検知し、その後に話した内容をClaude Codeへ渡すオープンソースのコマンドラインツールです。Anthropicが提供するClaude本体の新機能ではなく、GitHub上で公開されている別プロジェクトなので、ClaudeのアカウントやClaude Codeの利用環境は別に必要です。

公式リポジトリの説明では、マイク入力からウェイクワードを判定し、音声を文字に変換したうえで claude --bg を実行します。つまり、Claudeの画面を開いて入力欄へ文字を打つ代わりに、Macへ開発指示を話しかけるための補助ツールです。プロジェクトの概要とライセンスはGitHubのhey-claudeリポジトリで確認できます。

公式Claudeの音声会話との違い — 常時待機ではなく開発指示向け

検索時に混同しやすいのが、Claudeアプリの音声会話です。Anthropic公式の案内では、ClaudeはWeb、デスクトップ、iOS、Androidなどから利用できます。一方、hey-claudeはClaudeの会話画面を音声化する機能ではなく、Macのマイクを待機させてClaude Codeのコマンドを起動する仕組みです。Claudeの利用先は公式ヘルプの利用開始ガイドで確認できます。

違いを整理すると、次のようになります。

「Claudeに質問したい」だけなら公式アプリの利用が分かりやすく、「ターミナルで動かす開発作業を声で始めたい」ならhey-claudeが候補になります。

できることと仕組み — 4段階で音声をコマンドに変える

hey-claudeは、音声をそのままクラウドへ送って判定するのではなく、呼びかけの検知と指示の文字起こしをMac側で処理します。公式リポジトリでは、処理を次の流れとして説明しています。

1. マイクから音声を受け取り、openWakeWordで「hey claude」を判定する。
2. 呼びかけの後に続く指示を、無音が続くまで録音する。
3. MLX Whisperで音声をテキストへ変換する。
4. 変換した指示を単一の引数として claude --bg に渡す。

この構成の利点は、呼びかけを待つ小さな判定処理と、指示の文字起こしをローカルで完結できることです。PyPIのhey-claudeプロジェクトページにも、最終的に送られるのはClaude Codeへ渡す指示であり、それ以前の処理はMac上で行うと記載されています。ただし、Claude Codeへ渡した指示の扱いは、通常のClaude Code利用時と同じように考える必要があります。

対応環境と必要なもの — Apple Silicon Macが前提

導入前に、次の条件を確認してください。Intel Mac、Windows、Linux向けのビルドは案内されていないため、Macなら何でも動くわけではありません。

Apple Silicon上のMLXを使って音声を処理するため、Intel Macでは同じ構成を利用できません。また、hey-claudeを入れてもClaude Code自体はインストールされません。Claude Codeのログイン、料金プラン、権限設定は別途確認しておきましょう。

インストール手順 — Homebrewとpipxで導入

公式のPyPIページでは、PortAudioを用意してから、仮想環境を扱いやすいpipxで導入する方法が示されています。Macのターミナルで次の順番に進めます。

1. Apple Silicon、Pythonのバージョン、Claude Codeの導入状況を確認する。

   uname -m
   python3 --version
   claude --version
   

2. Homebrewで音声入力のシステム依存関係を入れる。

   brew install portaudio
   

3. hey-claudeをインストールする。通常はPyPI版、再現性を優先する場合はGitHubのタグを指定する。

   pipx install hey-claude
   # または公開タグを固定する場合
   pipx install git+https://github.com/tachyurgy/hey-claude@v0.3.0
   

4. 初回診断を実行し、不足している依存関係を確認する。

   hey-claude doctor
   

pipxを使わない場合は、PyPIページにある pip install hey-claude も選べます。ただし、既存のPython環境を汚しにくい点では、プロジェクトが案内するpipxの方が扱いやすいでしょう。公開ページのバージョンやインストール方法は更新される可能性があるため、実行前にPyPIの最新版情報を確認してください。

初回設定と使い方 — マイク許可から実行まで

インストールできたら、まずターミナルから待機を開始します。最初の起動ではmacOSがマイクの利用許可を求めるので、内容を確認して許可してください。

1. ターミナルで hey-claude を実行する。

   hey-claude
   

2. macOSのマイク許可が表示されたら「許可」を選ぶ。

3. 起動音などを確認してから、「Hey Claude」に続けて指示を話す。たとえば「Hey Claude, add type hints to utils.py and run the tests」のように、対象と作業内容を具体的に伝える。

4. Claude Code側で処理が始まったことを確認し、必要なファイル変更やコマンド実行の許可を出す。

ログイン時にも自動で待機させたい場合は、hey-claude app でアプリケーションを作成し、~/Applications/Hey Claude.app を一度開いてマイク許可を与えます。その後、macOSの「システム設定」→「一般」→「ログイン項目」に追加します。ログイン時に起動する仕組みでは、ターミナルと違って許可ダイアログを表示できないことがあるため、先にアプリとして許可を済ませるのがポイントです。

認識精度と起動方法を調整する — モデル・threshold

初期状態では hey_claude モデルが使われます。周囲の会話で誤って反応する、反対に呼びかけを聞き逃すといった場合は、モデルや判定しきい値を調整できます。

1. 利用できるウェイクワードを確認する。

   hey-claude models
   

2. 誤反応が多いときは、別の呼びかけへ切り替える。

   hey-claude models use hey_computer
   

3. 反応しすぎる場合は threshold を上げ、聞き逃しが多い場合は少し下げる。

   hey-claude config set threshold 0.6
   

4. ウェイクワード用モデルを使わず、Whisperで判定する場合はエンジンを切り替える。

   hey-claude config set engine whisper
   

公式ページでは、okay_claude、hey_computer、hey_assistant などのモデルも案内されています。部屋の反響、マイクの品質、話者のアクセントで認識率は変わるため、数値だけでなく実際の環境で試して調整してください。設定ファイルの場所は hey-claude config path でも確認できます。

安全に使うための注意点とFAQ

マイクは常に待機するのか

起動中はウェイクワードを待つため、マイク入力を扱います。ローカル処理が中心でも、機密情報や他人の会話を意図せず拾わないよう、会議中は停止する運用が安全です。不要なときは Ctrl+C で終了し、ログイン時の自動起動も必要な時間帯だけ有効にしてください。

声で話した指示だけでファイルが変更されるのか

音声で指示を送れても、Claude Codeの権限確認を無条件に省略するものではありません。デフォルトの確認フローを残し、対象ファイルと実行コマンドを画面で確認してから許可します。自動承認に相当する設定を使う場合は、作業ディレクトリ、同時実行数、確認設定を先に限定してください。音声認識の誤りがそのまま作業内容になる可能性もあります。

WindowsやIntel Macで使えるのか

公開されている要件はmacOSとApple Siliconです。Windows、Linux、Intel Macで同じ手順を実行することはできません。公式Claude自体は複数の端末から利用できますが、hey-claudeのローカル音声処理とは対応範囲が異なります。

料金はかかるのか

hey-claude自体はMITライセンスで公開されているプロジェクトです。ただし、Claude Codeの利用料金や契約条件、音声指示を処理するClaude側の利用枠は別に発生します。無料でインストールできることと、Claude Codeを無制限に使えることは同じではありません。

出典: hey-claude GitHubリポジトリ / PyPI hey-claude / Claude公式ヘルプ「Get started with Claude」