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 – 面向代码生成代理的语音优先监督

相关