handsfree

/handsfree — voice loop for Claude Code

Toggle hands-free voice mode for the current macOS session.

How it works

you (speak) -> SFSpeechRecognizer -> handsfree MCP channel -> Claude
                                                                 |
you (hear)  <- macOS `say` <- Stop hook reads response <---------+

After each assistant turn, the Stop hook:

1. Reads the response aloud with say (markdown/code fences stripped).
2. Plays a start beep, then listens via SFSpeechRecognizer.
3. Ends listening as soon as the trailing word is "over", or after 10s (with 3 countdown beeps and a final cutoff beep).
4. POSTs the transcript to http://127.0.0.1:<port>/inject with a per-session bearer token, which the MCP channel forwards as the next user prompt.

Toggling

• /handsfree on — set the active flag at ~/.claude/handsfree/active and kick off the loop with a short greeting (so the Stop hook fires).
• /handsfree off — clear the active flag. The Stop hook no-ops on the next turn and stops listening.
• /handsfree status — print on or off.

If invoked with no argument, toggle.

Behaviour rules (when this skill is active)

• Keep responses short and conversational. Each one is going to be read aloud — multi-screen output is annoying.
• Strip or skip large code blocks; the Stop hook already removes them from TTS, but you should also avoid generating them unprompted.
• If you need to ask a clarifying question, end with that question so the user knows it's their turn.
• The <channel source="handsfree"> events are user prompts spoken aloud. Treat them exactly like a typed user message.

Implementation

When the user invokes this skill, run:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/state.sh" ${1:-status}

…and then in your response either:

• confirm voice mode is now active and greet them briefly (so the Stop hook has something to TTS and the loop starts), or
• confirm it's off.

Do not TTS yourself in chat — the Stop hook does that automatically.