handsfree

claude-voice-handsfree

Hands-free voice mode for Claude Code on macOS. Speak to Claude, hear responses back. Each assistant turn is read aloud with the built-in say command, then a SFSpeechRecognizer listener opens for the next prompt — exactly the engine macOS Dictation uses, but with a control loop that ends on the word "over" or after a 10-second countdown.

The transcript flows back into the running Claude Code session via an MCP channel — no terminal scraping, no clipboard hacks, no keystroke injection.

you (speak) ──► SFSpeechRecognizer ──► handsfree MCP channel ──► Claude
                                                                    │
you (hear)  ◄── macOS `say`         ◄── Stop hook reads response ◄──┘

Requirements

• macOS (uses say, afplay, SFSpeechRecognizer)
• bun — brew install oven-sh/bun/bun
• Xcode Command Line Tools — xcode-select --install (for swift)
• python3 (ships with Xcode CLT)
• Claude Code v2.1.81+ (channels capability)

Install

Option A — marketplace (recommended)

# inside a Claude Code session
/plugin marketplace add FarisHijazi/claude-voice-handsfree
/plugin install handsfree@claude-voice-handsfree

Then restart Claude Code so the MCP server + hooks load.

Option B — local install script

If you'd rather have the skill live at ~/.claude/skills/handsfree and skip the marketplace machinery:

git clone https://github.com/FarisHijazi/claude-voice-handsfree ~/projects/claude-voice-handsfree
cd ~/projects/claude-voice-handsfree
./install.sh

That script:

1. bun installs the plugin's dependencies.
2. Symlinks plugins/handsfree/skills/handsfree → ~/.claude/skills/handsfree.
3. Adds the Stop hook to ~/.claude/settings.json.
4. Adds the handsfree MCP server to ~/.claude.json.

To remove all of that: ./install.sh --uninstall.

Usage

/handsfree on

Claude will reply with a short greeting (which the Stop hook reads aloud) and then start listening. From that point on:

• Speak your message.
• Say "over" to finish.
• Or just stop talking — at 7s, 8s, 9s you'll hear countdown beeps, and at 10s a final cutoff beep plays and whatever you've said so far is sent.

When you're done:

/handsfree off

The Stop hook stops doing anything on the next turn.

macOS permissions

The first time the Swift listener runs, macOS will pop a prompt asking for Microphone and Speech Recognition access for the terminal app you're running Claude Code from (Terminal, iTerm, Ghostty, Warp…). Grant both. You can revoke later in System Settings → Privacy & Security.

Configuration

Environment variables, set in your shell or in a Claude Code launch wrapper:

var	default	what it does
HANDSFREE_PORT	8779	port the MCP channel listens on (127.0.0.1 only)
HANDSFREE_VOICE	(system)	macOS voice for say — e.g. Samantha, Daniel, Karen
HANDSFREE_RATE	190	say words-per-minute
HANDSFREE_MAX	1500	truncate TTS after this many cleaned-up chars
LISTEN_MAX	10	max dictation seconds before cutoff
LOCALE	en-US	locale passed to SFSpeechRecognizer (e.g. ar-SA, fr-FR)
END_WORD	over	trailing keyword that ends dictation early

How it actually works

1. MCP server (server.ts). Bun process spawned by Claude Code over stdio. Declares the claude/channel capability so it can push events into the session. Also binds 127.0.0.1:HANDSFREE_PORT for a single POST /inject endpoint, gated by a per-session bearer token written to ~/.claude/handsfree/token (mode 0600).

2. Stop hook (scripts/stop-hook.sh). Fires whenever Claude finishes a turn. If ~/.claude/handsfree/active exists and stop_hook_active is false (no re-entry), it:

   • parses the JSONL transcript at transcript_path,
   • extracts the most recent assistant text,
   • pipes it through scripts/speak.sh (strips fenced code blocks, inline code, markdown links, URLs; truncates to HANDSFREE_MAX) and into say,
   • runs swift scripts/listen.swift to dictate the next prompt,
   • curls the transcript to POST /inject with the bearer token.

3. Dictation (scripts/listen.swift). AVAudioEngine + on-device SFSpeechRecognizer for streaming partials. Detects the trailing word over and ends immediately; otherwise plays a beep at 7s/8s/9s and a cutoff beep at 10s. Strips the trailing over from output before printing.

4. Channel notification. The MCP server emits

   <channel source="handsfree" source="dictation" ts="...">
   …transcript…
   </channel>