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가 끝나면 테스트를 다시 실행해"와 같은 더 풍부한 명령어가 가능합니다.
• 스크린으로의 백업 – TapQ가 제스처를 해석하지 못하거나 음성 창이 타임아웃되면 원래의 화면 프롬프트가 그대로 표시됩니다.
• 로컬 기반 개인정보 보호 설계 – 모션 및 제스처 처리는 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 – 훅과 런타임 사이를 매개하는 로컬 소켓 브로커.
• 각 에이전트별 어댑터 타겟(TapQClaudeAdapter, TapQCodexAdapter 등)으로 훅 이벤트를 번역.
• TapQAppleAdapters 및 TapQVoiceBackends – macOS 전용 모션, 음성, OpenAI 실시간 통합.
• TapQCLI – 명령줄 인터페이스(tapq 및 에이전트별 훅 바이너리).

라이선스 – Apache 2.0 (소스만 제공; Homebrew 포뮬러나 서명된 바이너리 아직 없음).

위치 – TapQ는 일반 목적의 어시스턴트가 아니라, 여러 코드 에이전트를 감시할 때 화면을 보지 않고도 물리적 세계(이어버드, 머리 제스처)에 머무를 수 있도록 해주는 상호작용 계층입니다.