cvi

CVI (Claude Voice Integration)

Claude Codeのタスク完了時に音声通知を行うシステム

---

概要

CVIは、Claude Codeの作業を音声でフィードバックするhooksシステムです。

特徴

• 🔊 音声通知: タスク完了を音声で通知（/cvi:speak Skill tool使用）
• ⏸️ 自動中断: 読み上げ中に新しい指示を出すと自動停止
• 🌐 多言語対応: 日本語・英語を自動判定
• 🔒 プロジェクト分離: 複数プロジェクトの音声が干渉しない
• 🛡️ 堅牢性: エラーログ、依存関係チェック、自動ロッククリーンアップ
• 🎯 推奨: /cvi:speak Skill tool（[VOICE]タグは非推奨）

---

必要環境

• OS: macOS（say, afplay, osascript コマンド使用）
• Claude Code: 最新版
• uv: MCP server の Python 依存解決に使用（brew install uv）
  • MCP server は uv run --script で自動的に temporary venv を作成し、user の site-packages を汚染せず動作する
  • PEP 668 制約のある macOS Homebrew / Xcode Python を回避

---

インストール

プラグインとしてインストール（推奨）

Claude Codeのプラグインシステムを使用してインストールできます：

# Claude Codeで以下のコマンドを実行
/plugin add signalcompose/cvi

これだけで完了です。hooks、コマンド、スキル、MCP server (cvi-voice) が自動的に設定されます。

MCP server の起動について

cvi-voice MCP server は uv run --script で自動起動します。初回のみ uv が mcp パッケージを temporary venv に解決する時間（数秒）がかかりますが、 以降は cached されます。ユーザー側で追加 install の作業は不要です。

uv が PATH に無い場合は MCP server 起動に失敗し、Claude Code 側で cvi-voice tool が登録されません。その際は brew install uv 後に Claude Code を再起動してください（Bash fallback について も参照）。

初期設定

インストール後、必要に応じて設定を調整：

/cvi:speed 200    # 読み上げ速度（デフォルト: 200wpm）
/cvi:lang ja      # [VOICE]タグ言語（デフォルト: ja）
/cvi:voice list   # 利用可能な音声を確認

---

手動インストール（非推奨）

手動セットアップは 非推奨です。Claude Code のプラグインシステムが登場する前の 手順であり、現在の MCP server + hooks + commands + skills を全て自前で配線する 必要があります。プラグイン経由のインストール（上記）を強く推奨します。

どうしても手動構成が必要な場合は scripts/cvi-setup を参照してください。

---

使い方

基本的な使い方

1. Claude Codeでタスクを実行
2. タスクが完了すると音声通知
3. 読み上げ中に新しい指示を出すと自動停止

制御コマンド

cvi - 音声通知の有効/無効

cvi on       # 音声通知を有効化
cvi off      # 音声通知を無効化
cvi show     # 現在の設定を表示
cvi help     # ヘルプを表示

cvi:speed - 読み上げ速度の調整

cvi:speed           # 現在の速度を確認
cvi:speed 220       # 速度を220wpmに設定
cvi:speed reset     # デフォルト（200wpm）に戻す

推奨速度：

• 180 wpm: ゆっくり、聞き取りやすい
• 200 wpm: 標準速度（デフォルト）
• 220 wpm: やや速め、効率的

cvi:lang - 言語切り替え

cvi:lang           # 現在の言語を確認
cvi:lang ja        # 日本語に設定
cvi:lang en        # 英語に設定
cvi:lang reset     # デフォルト（ja）に戻す

言語設定の役割：

• 日本語（ja）: フォールバックメッセージが日本語になります
• 英語（en）: フォールバックメッセージが英語になります

注意:

• 実際の読み上げ音声はcvi:voiceで設定します
• 日本語モードでは常にシステムデフォルト音声を使用
• 英語モードではcvi:voiceで設定した音声を使用
• [VOICE]タグ内のテキストは言語設定に関わらずそのまま読み上げられます

cvi:voice - 音声の選択（言語別設定）

cvi:voice                    # 現在の設定を確認
cvi:voice en Zoe             # 英語音声をZoeに設定
cvi:voice ja Kyoko           # 日本語音声をKyokoに設定
cvi:voice mode auto          # 自動音声選択モード（デフォルト）
cvi:voice mode fixed         # 固定音声モード
cvi:voice fixed Zoe          # 全言語でZoeを使用
cvi:voice list               # 利用可能な音声一覧
cvi:voice reset              # デフォルトに戻す

言語別音声設定:

• 英語音声 (cvi:voice en [VOICE]): 英語テキスト用の音声
• 日本語音声 (cvi:voice ja [VOICE]): 日本語テキスト用の音声
• 各言語で異なる音声を設定できます

音声モード:

• autoモード (デフォルト): 言語に応じて自動的に音声を切り替え
• fixedモード: 全ての言語で同じ音声を使用

人気の音声:

日本語:

• system: システムデフォルト（日本語Siri）
• Kyoko: 標準日本語音声（女性）
• Otoya: 標準日本語音声（男性）

英語:

• system: システムデフォルト（英語Siri）
• Samantha (US): 標準的でクリアな女性の声
• Zoe (UK): プレミアム女性音声
• Karen (AU): オーストラリア英語、女性
• Daniel (UK): イギリス英語、男性

cvi:auto - 言語自動検出

cvi:auto           # 現在の設定を確認
cvi:auto on        # 言語自動検出を有効化
cvi:auto off       # 言語自動検出を無効化（デフォルト）
cvi:auto status    # 詳細ステータス表示

言語自動検出:

• [VOICE]タグ内のテキストを分析し、日本語/英語を自動判定
• 日本語検出時 → 日本語音声を使用
• 英語検出時 → 英語音声を使用
• 設定言語に関わらず、適切な音声で読み上げ

使用例:

# 日本語環境で英語学習
cvi:lang ja            # フォールバックは日本語
cvi:voice ja system    # 日本語はシステム音声
cvi:voice en Zoe       # 英語はZoe（学習用）
cvi:auto on            # 自動検出ON

# 動作
[VOICE]Task completed[/VOICE]  # Zoeで英語読み上げ
[VOICE]完了しました[/VOICE]      # システム音声で日本語

cvi:check - セットアップ診断

cvi:check          # セットアップ状態を診断

チェック項目：

• Siri音声設定
• スクリプト実行権限
• hooks設定
• 読み上げ速度
• 言語設定

[VOICE]タグの使用

Claude Codeのレスポンスに[VOICE]...[/VOICE]タグを含めると、その部分が読み上げられます：

詳細な技術的説明が続く...

[VOICE]ファイルの編集が完了しました。3つのファイルを更新しました。[/VOICE]

タグがない場合は、メッセージの最初の200文字が自動的に読み上げられます。

Siri音声の使用（推奨）

より自然で流暢な読み上げのため、Siri音声を設定してください：

1. システム設定 > アクセシビリティ > 読み上げコンテンツ
2. システムの声で「Siri (声2)」または「Eloquence」を選択
3. CVIは自動的にシステムデフォルト音声を使用

確認方法：

say "これはテストメッセージです"

Siri音声で読み上げられれば、CVIでも同じ音声が使われます。

---

高度なカスタマイズ

音量調整

~/.claude/scripts/notify-end.shの以下の行を編集：

# 音声読み上げ音量を変更（0.0〜1.0）
afplay -v 0.6 "$TEMP_AUDIO"  # デフォルト: 0.6（60%）

# 通知音の音量を変更（0.0〜1.0）
afplay -v 1.0 /System/Library/Sounds/Glass.aiff  # デフォルト: 1.0（100%）

通知音の変更

Glass音以外を使用する場合：

# 利用可能な音を確認
ls /System/Library/Sounds/

# notify-end.sh内で別の音に変更
afplay -v 1.0 /System/Library/Sounds/Ping.aiff &

---

技術仕様

アーキテクチャ

実行経路: MCP 一本化

/cvi:speak は MCP server 経由のみ。Bash fallback は #242 で撤廃（MCP を 作った意図を明確化、parrotvox 移行 Phase 5 に向けた単純化）。