spaceamoeba-t/tapq

Multi-modal voice agent for your AI agents. Talk with Claude Code, Codex, and others by voice: answer their prompts, give instructions, ask what they did. Or just nod.

TapQ – 面向程式生成代理的語音優先監控

是什麼 – TapQ 是一個基於 Swift 的執行時，位於你與程式生成代理（Claude Code、Codex、Cursor、OpenCode）之間。當代理需要你批准、選擇或後續指示時，TapQ 會透過你的 AirPods（或任何 macOS 音訊裝置）將提示內容朗讀出來，讓你無需查看螢幕即可完成互動。你的回應可透過雙點頭／雙搖晃手勢、莖部滑動或語音輸入來捕捉。

核心功能

語音提示 – 當代理暫停等待權限、問題或選擇時，TapQ 會在你耳邊朗讀提示，前綴為代理名稱（例如：「Claude Code：執行 swift test。批准？」）。
手勢驅動回應 – 雙點頭表示批准，雙搖晃表示拒絕，傾斜用於在選項間移動，輕觸確認選擇。所有運動資料均在裝置本地處理。
語音互動 – 使用 --voice-backend openai-realtime 時，語音回應會傳送至 OpenAI 的即時 API（僅在回應視窗開啟期間），可用於更豐富的指令，如「執行測試並告訴我是否有失敗」或「當 Claude 完成後，重新執行測試」。
回落到螢幕 – 如果 TapQ 無法解讀手勢或語音視窗超時，原始螢幕提示將原樣顯示。
本地優先的隱私設計 – 運動和手勢處理完全在 Mac 上進行；音訊僅在回應視窗開啟時傳送至 OpenAI；本地對話日誌（wearer-conversation.jsonl）限制為 30 天，可透過 tapq memory clear 命令清除。

工作原理

代理鈎子 – tapq integration <agent> install 將一個小鈎子或外掛注入目標代理。當代理需要使用者決策時，鈎子將事件轉送給 TapQ 執行時並等待回覆。
執行時 – 執行時將提示排隊，透過耳機播放，開啟短暫的「回應視窗」，並監聽手勢或語音。
手勢引擎 – AirPods 的 CoreMotion 資料在裝置上解析，以檢測雙點頭、雙搖晃、雙傾斜和莖部輕觸／滑動。
語音後端 – 可選擇本地固定詞彙識別器（無需 API 金鑰）或 OpenAI 的即時 API，將語音轉換為支援的操作（批准、拒絕、選擇選項、排隊指令、詢問狀態、設定後續任務、啟動任務）。
結果路由 – 回覆透過鈎子返回原始代理。若未產生回覆，鈎子將不回傳回覆，代理將回落到其正常 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 授予運動、語音、麥克風權限）
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 – 本地套接字代理，用於在鈎子與執行時之間進行中介。
每個代理一個適配器目標（TapQClaudeAdapter, TapQCodexAdapter 等）用於翻譯鈎子事件。
TapQAppleAdapters 與 TapQVoiceBackends – macOS 特有的運動、語音和 OpenAI 即時整合。
TapQCLI – 命令列介面（tapq 和各代理鈎子二進位檔）。

許可證 – Apache 2.0（僅原始碼；尚未提供 Homebrew 公式或簽署二進位檔）。

定位 – TapQ 並非通用助理，而是一個 互動層，讓你在監控多個程式生成代理時，無需盯著螢幕，即可停留在物理世界（耳機、頭部手勢）中。

spaceamoeba-t/tapq

TapQ – 面向程式生成代理的語音優先監控

相關