spaceamoeba-t/tapq

TapQ – コード生成エージェント向け音声優先の監視

何であるか – TapQ は Swift で構築されたランタイムで、あなたとコード生成エージェント（Claude Code、Codex、Cursor、OpenCode）の間に位置します。エージェントが承認、選択、または追加指示を求める際、TapQ はそれらを AirPods（または任意の macOS 音声デバイス） を通じてあなたの耳に読み上げます。画面を見ることなく、双方向のやり取りが可能になります。あなたの応答は、二重うなずき／二重シェイク、ステムスワイプ、または音声で取得されます。

主な機能

• 音声によるプロンプト – エージェントが承認や質問、選択を待つ際、TapQ はプロンプトを耳元で読み上げ、エージェント名を前置します（例：「Claude Code: swift test を実行しますか？承認？」）。
• ジェスチャーによる応答 – 二重うなずきで承認、二重シェイクで拒否、傾きでオプション間を移動、タップで選択を確定。モーションデータはすべてデバイス内処理。
• 音声インタラクション – --voice-backend openai-realtime を使用すると、音声応答は OpenAI のリアルタイム API に送信されます（応答ウィンドウが開いている間のみ）。より豊かなコマンド（例：「テストを実行して失敗した箇所を教えて」や「Claude が終了したらテストを再実行」）が可能になります。
• スクリーンへのフォールバック – ジェスチャーが解釈できない、または音声ウィンドウがタイムアウトした場合、元のスクリーン上のプロンプトがそのまま表示されます。
• ローカルプライバシー最優先設計 – モーションとジェスチャー処理は Mac 上で完結。音声は応答ウィンドウ開設時のみ OpenAI に送信。ローカルの会話ログ（wearer-conversation.jsonl）は30日間で制限され、tapq memory clear コマンドで削除可能。

動作方法

1. エージェントフック – tapq integration <agent> install で、ターゲットエージェントに小さなフックまたはプラグインを挿入。エージェントがユーザーの判断を必要とする際、フックはイベントを TapQ ランタイムに転送し、返答を待機します。
2. ランタイム – プロンプトをキューに登録し、イヤホン経由で読み上げ、短い「応答ウィンドウ」を開き、ジェスチャーや音声を待機します。
3. ジェスチャーエンジン – AirPods からの CoreMotion データをデバイス内で解釈し、二重うなずき、二重シェイク、二重傾き、ステムタップ／スワイプを検出します。
4. 音声バックエンド – ローカルの固定語彙認識（APIキー不要）または OpenAI のリアルタイム API により、音声を承認、拒否、オプション選択、指示キュー、ステータス確認、フォローアップ設定、タスク開始などの対応アクションに変換します。
5. 結果ルーティング – 応答はフック経由で元のエージェントに送信されます。応答が得られなかった場合、フックは応答なしで返却され、エージェントは通常の UI にフォールバックします。

対応プラットフォーム・デバイス

• macOS 14+（Swift 6、Xcode 16 または互換ツールチェイン） – AirPods 統合を含む完全なランタイム。
• Linux – ポータブルコアと CLI はビルド・テスト可能ですが、イヤホンやエージェントフックは非対応。
• AirPods – ヘッドモーションを公開するモデル（AirPods Pro、AirPods 3+、AirPods Max）。ステムスワイプは AirPods Pro 2 以降が必要。
• エージェント – Claude Code（完全フック対応）、Codex CLI ≥ 0.142.5、Cursor（部分対応）、OpenCode ≥ 1.18.15（プラグイン経由）。

導入手順（macOS 14+、Swift 6、互換 AirPods 必須）

# クローンとビルド
git clone https://github.com/spaceamoeba-t/tapq.git
cd tapq
swift build && swift test

# モーション／音声権限のキャリブレーション（ヘッドレスアプリを実行し、macOS が Motion、Speech、マイク権限を付与）
scripts/run-runtime-app.sh calibration run

# 使用するエージェントのフックをインストール（例：Claude Code）
build/TapQRuntime.app/Contents/MacOS/tapq integration claude install --permission-policy native
# …必要に応じて codex, cursor, opencode についても繰り返し

# ランタイムを起動。以下の例では OpenAI リアルタイム音声バックエンドと wearer-gate を有効化。
scripts/run-runtime-app.sh serve \
  --voice-backend openai-realtime \
  --voice-instructions --voice-session \
  --wearer-gate --attention wake

エージェントが一時停止すると、耳元でプロンプトが聞こえ、うなずき、シェイク、傾き、タップ、または音声コマンドで応答できます。

プロジェクト構造

• TapQContracts – すべてのアダプタで共有される型とプロトコル。
• TapQDetectionBaseline, TapQInteractionBaseline, TapQContextBaseline – Linux 上でもビルド可能なポータブルコア（ジェスチャー検出、ステートマシン、メモリ）。
• TapQBrokerRuntime および TapQWireProtocol – フックとランタイムの間を仲介するローカルソケットブローカー。
• 各エージェントごとに1つのアダプタターゲット（TapQClaudeAdapter, TapQCodexAdapter など）でフックイベントを翻訳。
• TapQAppleAdapters および TapQVoiceBackends – macOS 固有のモーション、音声、OpenAI リアルタイム統合。
• TapQCLI – コマンドラインインターフェース（tapq およびエージェントごとのフックバイナリ）。

ライセンス – Apache 2.0（ソースのみ。Homebrew フォーミュラや署名付きバイナリは未提供）。

位置づけ – TapQ は汎用アシスタントではなく、複数のコード生成エージェントを監視する際、画面を見ずに物理世界（イヤホン、頭部ジェスチャー）に留まり続けられる インタラクションレイヤー です。