tapq

AI scales. Your attention doesn't. Agents work in parallel, and keeping them moving still pulls you back to a screen — to check, to answer, to approve. Checking fragments your focus: which agent finished, which one is stuck. Every switch costs context: open the tool, read the thread, find what needs you. Stepping away stops the work: a question or an approval sits unanswered until you return. You've delegated the work; staying in control still ties you to a screen.

Agents are the first software you don't operate but supervise, and supervision doesn't need a screen — it needs a way to reach you. TapQ is that way. Works today with Claude Code, Codex, Cursor, and OpenCode, on AirPods and macOS.

Contents

• What it does
• How it works
• Privacy and data
• Where TapQ fits
• Current support
• Controls
• Quick start
• FAQ
• Developer guide
• Documentation
• Community
• License

What it does

TapQ is a voice agent that runs in the background all day, connected to your coding agents through their hooks. It listens on-device, speaks only when an agent needs you or you speak to it, and hears your answer through the earbuds. Four things:

• Speaks every prompt. When Claude Code, Codex, Cursor, or OpenCode stops for an approval, a question, or a choice, TapQ says it in your ear: Claude Code: Run swift test. Approve? You answer "yes", double-nod, or tilt and tap through the options. Prompts from every open session arrive as one spoken queue.
• Reports a finished run and takes the next instruction. "Claude Code finished the migration." — "Tell it to rerun the tests." — "Queued for Claude Code." An agent's turn ends in your ear, and the next one starts there.
• Answers questions about the work. "Who's waiting?" "What did Codex change?" TapQ reads the agents' own transcripts and answers in a sentence instead of a tab.
• Takes goals and follow-ups. "Run the tests and tell me if anything fails." "When Claude Code finishes, rerun the tests." With nothing running at all, "Hey TapQ, set up a Swift package for the parser" starts a session.

An afternoon with two agents:

Claude Code: Run swift test. Approve?
  "yes"
Codex: Run python migrate.py. Approve?
  "no, tell Codex to keep the old table names"
  Queued for Codex.
  "who's waiting?"
  Nothing is waiting. Claude Code finished the migration.
  "when Claude Code finishes the changelog, rerun the tests"
  After Claude Code finishes: rerun the tests — noted.

Answering needs no wake word, nothing to open, nothing to look at. Anything TapQ cannot answer — a multi-select prompt, a missed gesture, a failed voice pipe — falls back to the agent's on-screen prompt exactly as if TapQ weren't installed. Everything TapQ does unprompted is spoken and attributed, and none of it can approve anything.

How it works

TapQ is a runtime on your Mac with an adapter for each agent and each device.

1. Hooks in the agents. tapq integration <agent> install adds a hook (Claude Code, Codex, Cursor) or a plugin (OpenCode) to the agent. When the agent stops for a permission, a question, or a choice, or finishes a turn, the hook sends that event to the runtime and waits for the answer.
2. Spoken in-ear, then a response window. The runtime speaks the prompt through the earbuds and listens for a set time. Prompts from several sessions queue and are spoken one at a time, each named with its agent.
3. Gestures from the motion stream. AirPods report head motion; TapQ recognizes a double nod, double shake, double tilt, and stem tap on-device and maps them to approve, deny, next or previous option, and confirm.
4. Speech through a voice backend. With --voice-backend openai-realtime, your speech is sent to OpenAI's realtime API only while a window is open, and the model turns what you said into one of a fixed set of actions: approve, deny, select an option, queue an instruction for an agent, answer a question about status or an agent's transcript, set a follow-up, or start a task. It can speak only what TapQ passes it; it cannot answer a prompt on its own. The default on-device backend matches a fixed vocabulary instead.
5. Wearer attribution. The same motion sensors register the vibration of your own speech. With --wearer-gate, speech that does not coincide with it is ignored, so a colleague or a video cannot answer for you.
6. Back through the hook, or back to the screen. The answer returns to the agent through its hook. If the window times out or nothing is recognized, the hook returns without an answer and the agent shows its normal on-screen prompt.
7. Between prompts. With --attention wake, an on-device recognizer listens for "hey tapq" whenever nothing else is listening and opens a window with the same rules; with no session running, a sentence starts one. What you and TapQ say to each other is appended to a local file, and a recent slice of it is given to the model each turn so it can resolve "the thing I asked about earlier".

Privacy and data

TapQ sits between you and tools that can run commands, so the boundaries are part of the design, not a settings page. What ships today:

• Head motion is read only inside a window. The motion stream opens when TapQ speaks a prompt or hears the wake word and stops when the window resolves. Between windows, a nod at a colleague does nothing in TapQ.
• Gesture recognition and wearer attribution run on-device. Nothing leaves the Mac to decide whether you nodded or whether the voice was yours.
• Speech leaves the Mac only if you opt in, and only inside a window. The default backend matches a fixed vocabulary on-device with no API key. With --voice-backend openai-realtime, audio goes to OpenAI's realtime API only while a response window is open; wake-word listening between windows stays on-device.
• Conversation memory is local, bounded, and yours to clear. With the realtime backend, what you and TapQ said to each other is appended to wearer-conversation.jsonl in the runtime directory. It keeps 30 days or a couple of megabytes, whichever comes first, and tapq memory clear wipes it. Tool inputs, working directories, and permission modes are never spoken and never recorded.
• Nothing TapQ does on its own can approve anything. Follow-ups, goals, and the deliberation loop can queue an instruction or say a sentence; every approval still comes from your gesture or your voice. The risk reasoner is escalation-only: it can raise the confirmation bar for a prompt and can do nothing else.
• Failure falls back to the screen. A timed-out window, a missed gesture, or a dead voice pipe returns the prompt to the agent's own on-screen flow.

The local broker boundary describes what the hooks and the runtime can and cannot do to each other. Privacy principles sets the rules for planned capture modes (explicit start, clear state, consent first) that shipped functionality will be held to.

Where TapQ fits

Nodding to answer an earbud is no longer exotic. Siri Interactions on AirPods let you nod yes or shake no to Siri, and every coding agent now offers some way to approve a prompt from a phone. TapQ is for the gap between them: