VoiceLayer

Your AI agent can't hear you and respond to you. VoiceLayer gives it ears and a voice.

Voice I/O for AI coding assistants. Press F5, speak to Claude Code, get on-device transcription in under 1.5 seconds. Your AI speaks back. Works with any MCP client.

On a mouse with side buttons, button 5 (forward) works like F5 and button 4 (back) presses Return.

Select text in any app and press Option+F5 to read it aloud; press it again to stop. Shift+F5 re-pastes the last transcript. Option+F5 is ignored during dictation or transcription. Secure fields are never read. If a safe clipboard backup is unavailable, the shortcut asks you to retry and leaves the clipboard intact.

  You ──🎤──> whisper.cpp ──> Claude Code ──> edge-tts ──🔊──> You
         STT (local)           MCP tools         TTS (free)

Local-first. Free. Open-source. No cloud APIs, no API keys, no data leaves your machine.

Website · Docs · npm

Install

macOS (recommended) — the tap ships the CLI/MCP package and the notarized notch app:

If brew help trust reports an unknown command, update Homebrew first.

brew tap etanhey/layers
brew trust etanhey/layers                     # allow Homebrew to load this tap
brew install etanhey/layers/voicelayer         # CLI + MCP server
brew install --cask etanhey/layers/voicebar    # VoiceBar notch app (owns the mic)
voicelayer setup                               # one-time runtime setup

Install the cask too — the formula alone gives you the CLI/MCP but no notch UI.

brew tap adds the repository; brew trust etanhey/layers explicitly trusts its current and future formulae, casks and commands. Fully qualified installs trust only the named item. See Homebrew tap trust for item-specific alternatives.

npm — if you only want the MCP server:

bun add -g voicelayer-mcp        # or: npm i -g voicelayer-mcp
brew install sox socat && pip3 install 'edge-tts>=7.3.1'
brew install whisper-cpp         # optional, for local STT

# whisper model (~1.5 GB) — needed for local STT
mkdir -p ~/.cache/whisper && curl -L -o ~/.cache/whisper/ggml-large-v3-turbo.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

Speak from the terminal

voicelayer speak "Hello"
echo "Text to read" | voicelayer speak
voicelayer speak - --markdown
voicelayer speak --file notes.md --profile long --wait
voicelayer speak --stop

Speech goes through the running VoiceLayer daemon, sharing Stop and the teleprompter. With the daemon, the command returns after the first audio starts; --wait waits for completion. --profile auto is the default; short and long select the corresponding profile. Auto selects the saved long profile above short_limit_chars and the short profile at or below the threshold (default: 400 characters). --profile short|long overrides that choice. Markdown conversion defaults on for .md files; literal text and stdin are plain unless --markdown is supplied. Long reads stream chunks without the MCP tool's text cap, up to the shared 200,000-character safety limit.

If the daemon is unavailable, the CLI reports it on stderr and runs the same streaming engine in the foreground, waiting for completion even without --wait. Ctrl-C stops local synthesis/playback and waits for owned children to exit. Local fallback has no teleprompter; --stop requires the daemon. Authentication, busy, synthesis and playback failures return a nonzero exit code. Failures after an async daemon command has returned are reported by the daemon; use --wait when the final exit status matters. An older running daemon must be updated/restarted to support this command.

Speech credentials resolve in this order: VOICELAYER_DAEMON_SECRET_PATH, isolated VOICELAYER_STATE_DIR, an MCP socket override, VOICELAYER_TTS_DAEMON_SECRET_FILE, VOICELAYER_TTS_AUTH_TOKEN_FILE, then ~/.voicelayer/daemon.secret. Isolation paths take precedence over inherited TTS aliases. Secret files must be regular, nonempty, non-symlink files with mode 0600.

Point your MCP client at the daemon

VoiceLayer runs as one persistent daemon on a Unix socket; every session connects through a lightweight socat shim instead of spawning its own process. Add to .mcp.json:

{
  "mcpServers": {
    "voicelayer": {
      "command": "socat",
      "args": ["STDIO", "UNIX-CONNECT:/tmp/voicelayer-mcp.sock"]
    }
  }
}

Or migrate every repo at once: bash scripts/migrate-to-daemon.sh (--dry-run to preview). On macOS, grant your terminal microphone access (System Settings → Privacy → Microphone).

Updates, kill-switches, and cross-machine setup: docs/install-and-update.md.

Related MCP server: io.github.chicogong/ffvoice

The two tools

Both ship full MCP ToolAnnotations. Neither is destructive; both set openWorldHint: false.

Daemon speech profiles, env overrides, and socket controls: docs/tts-settings.md.

How voice_ask works: waits for any playing audio to finish → speaks the question via edge-tts → records the mic and resamples to 16kHz → Silero VAD detects when you stop talking → whisper.cpp transcribes locally (~200-400ms on Apple Silicon) → returns the text to your agent. Ask parks a live read and resumes it at the parked word as soon as answer capture ends, with the transcription spinner in the left wing. A manually paused read stays parked while Ask speaks and records; afterwards it returns still paused, ready to resume at the same word.

Predominantly Hebrew questions use he-IL-HilaNeural when an English Edge voice is selected. Clone selections stay as configured. If Edge synthesis exhausts its retries, Ask shows the question in an MCP warning notification and still records the answer. The saved exchange marks prompt_delivery: "text-only" (schema 5) and retains the question text and answer WAV without inventing prompt audio.

Full tool parameters: docs/tools-reference.md.

VoiceBar — the notch surface (macOS)

The canonical UI (SwiftUI + AppKit). It tucks around the MacBook camera housing instead of floating over your work:

• Liquid-Glass wings flank the camera housing, with a graceful fallback on older macOS.

• Teleprompter with word-by-word karaoke highlighting as your agent speaks.

• Idle-hover to summon — collapsed it draws no pixels; hovering reveals the mic, History and Settings.

• Settings — General · Models · Dictionary · History. Open with ⌘, or right-click → Settings…, or from a script: open voicebar://settings/models.

• Morph animations between idle ↔ recording ↔ speaking, Reduce-Motion aware.

STT backends

Auto-detected. Override with QA_VOICE_STT_BACKEND=whisper|wispr|auto.

Platform support

Part of Golems

Pair with BrainLayer to remember voice conversations across sessions.

More

• Architecture — why one daemon instead of a process per session

• Configuration — environment variables and test commands

• Contributing

License

Apache-2.0