Voice Mode for Claude Code

Voice Mode for Claude Code allows you to have a continuous two-way conversation with Claude Code, hands-free.

It uses the new Claude Code hooks to deliver voice input to Claude while it works.

This lets you speak continuously to Claude - interrupt, redirect, or provide feedback without stopping what Claude is doing.

Optionally enable text-to-speech to have Claude speak back to you.

Voice recognition and text-to-speech are handled by the browser, so there is nothing to download, and no API keys are needed.

Demo Video

Installation

Installation is easy.

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Install Voice Mode

npx mcp-voice-hooks@latest install-hooks
claude mcp add voice-hooks npx mcp-voice-hooks@latest

Usage

1. Start Claude Code

claude

2. Start Listening

The browser interface will automatically open after 3 seconds (http://localhost:5111).

Click "Start Listening"

3. Speak

Say something to Claude. You will need to send one message in the Claude Code CLI to start the conversation.

Browser Compatibility

• ✅ Chrome: Full support for speech recognition, browser text-to-speech, and system text-to-speech
• ⚠️ Safari: Full support for speech recognition, but only system text-to-speech is supported
• ❌ Edge: Speech recognition not working on Apple Silicon (language-not-supported error)

Voice responses

There are two options for voice responses:

1. Browser Text-to-Speech
2. System Text-to-Speech

Selecting and downloading high quality System Voices (Mac only)

Mac has built-in text to speech, but high quality voices are not available by default.

You can download high quality voices from the system voice menu: System Settings > Accessibility > Spoken Content > System Voice

Click the info icon next to the system voice dropdown. Search for "Siri" to find the highest quality voices. You'll have to trigger a download of the voice.

Once it's downloaded, you can select it in the system voice menu.

Test it with the bash command:

say "Hi, this is your Mac system voice"

To use Siri voices with voice-hooks, you need to set your system voice and select "Mac System Voice" in the voice-hooks browser interface.

Other downloaded voices will show up in the voice dropdown in the voice-hooks browser interface so you can select them there directly, instead of using the "Mac System Voice" option.

Manual Hook Installation

The hooks are automatically installed/updated when the MCP server starts. However, if you need to manually install or reconfigure the hooks:

npx mcp-voice-hooks install-hooks

This will configure your project's .claude/settings.local.json with the necessary hook commands.

Uninstallation

To completely remove MCP Voice Hooks:

# Remove from Claude MCP servers
claude mcp remove voice-hooks

# Also remove hooks and settings
npx mcp-voice-hooks uninstall

This will:

• Clean up voice hooks from your project's .claude/settings.local.json
• Preserve any custom hooks you've added

Development Mode

If you're developing mcp-voice-hooks itself:

# 1. Clone the repository
git clone https://github.com/johnmatthewtennant/mcp-voice-hooks.git
cd mcp-voice-hooks

# 2. Install dependencies
npm install

# 3. Link the package locally
npm link

# 4. Install hooks (one time)
npx mcp-voice-hooks install-hooks

# 5. Start Claude Code
claude

Important: When developing with npm link:

• Claude runs the compiled JavaScript from the dist folder, not your TypeScript source
• After making changes to TypeScript files (src/*.ts), you must run npm run build
• For changes to browser files (public/*), just restart Claude Code
• Then restart Claude Code to use the updated code

Configuration

Port Configuration

The default port is 5111. To use a different port, add to your project's .claude/settings.local.json:

{
  "env": {
    "MCP_VOICE_HOOKS_PORT": "8080"
  }
}

Browser Auto-Open

When running in MCP-managed mode, the browser will automatically open if no frontend connects within 3 seconds. To disable this behavior:

{
  "env": {
    "MCP_VOICE_HOOKS_AUTO_OPEN_BROWSER": "false"
  }
}

Auto-Deliver Voice Input Before Tools

By default, voice input is not automatically delivered before tool execution to allow for faster tool execution. To enable auto-delivery before tools:

{
  "env": {
    "MCP_VOICE_HOOKS_AUTO_DELIVER_VOICE_INPUT_BEFORE_TOOLS": "true"
  }
}

When auto-delivery before tools is enabled:

• Voice input is automatically delivered before each tool execution
• Tools may be delayed if there's pending voice input
• This ensures voice commands are processed before tools run
• Note: This setting only applies when MCP_VOICE_HOOKS_AUTO_DELIVER_VOICE_INPUT is enabled (default)

When auto-delivery before tools is disabled (default):

• Tools will execute immediately without checking for pending voice input
• Voice input will only be processed at the stop hook or post-tool hook
• Important: Delivered utterances that require voice responses will still be enforced
• This provides better performance when voice interruption before tools is not needed

Auto-Deliver Voice Input (Default)

By default, mcp-voice-hooks automatically delivers voice input to Claude after tool use, before speaking, and before stopping:

• The dequeue_utterances and wait_for_utterance MCP tools are hidden from Claude
• Voice input is automatically delivered when Claude performs any action
• Claude receives voice input naturally without needing to explicitly call mcp-voice-hooks tools

To disable auto-delivery:

{
  "env": {
    "MCP_VOICE_HOOKS_AUTO_DELIVER_VOICE_INPUT": "false"
  }
}

When auto-delivery is disabled:

• The dequeue_utterances and wait_for_utterance tools become visible
• Hooks no longer automatically process voice input
• Claude will be blocked from making tool calls until it manually dequeues voice input
• This mode is useful for debugging or when you want manual control