agent-notify

Local spoken notifications for Codex. Each message plays through your speakers and appears in a small always-on-top overlay.

Notifications can include a short source tag. Callers may also request a persistent overlay with an editable reply area. If TTS_MCP_REPLY_COMMAND is configured, that local command receives source and message as JSON on stdin; its stdout is used to prefill the reply area. Without a reply command, the area starts empty for manual typing.

The popup header also shows the originating working folder (for example, TWITCH • ~/code/twitch-mcp). Callers can override the automatically detected directory with the origin_folder tool argument.

Urgent notifications blink, never auto-close, and must be dismissed with their ACCEPT button. In a reply editor, Enter submits the reply and Shift+Enter adds a newline. Use OPTIONS to reset placement. Interactive notifications can be dragged by their title bar or header, and their position is saved for future messages. Opening Options pauses the overlay's close countdown until the panel is closed. The panel also selects the Coqui model used for subsequent local messages and lowers Spotify to a configurable percentage of its current volume while TTS is playing. The model menu includes Jenny; LJSpeech VITS, Tacotron2, Glow-TTS, SpeedySpeech, FastPitch, and Neural HMM variants; EK1 and SAM Tacotron models; and VCTK VITS or FastPitch with speaker p225. Models download on first use. Spotify's previous volume is restored when playback ends.

Spotify ducking defaults to 20% of its current volume. The Options choices are Off, 10%, 20%, 30%, 40%, and 50%. On Linux, tts-mcp prefers a matching PipeWire stream through pw-dump and wpctl, then falls back to Spotify's MPRIS volume property through busctl. If neither control path is available, TTS playback continues without changing Spotify.

The MCP server also exposes:

• list_voices — list local presets and optional OpenRouter Flux voices;

• preview_voices — play the same short phrase through up to six voices;

• quit_spotify — request a graceful Spotify quit, with an explicit forced fallback when requested.

Local voice previews include Jenny, LJSpeech VITS, and selected speakers from the VCTK VITS model. Models are downloaded by Coqui on first use and cached.

Install

Supports Python 3.11 through 3.14 and requires uv.

uv sync
uv run --no-sync agent-notify-setup
codex mcp add agent-notify -- "$(pwd)/.venv/bin/tts-mcp"

Restart Codex, then run /mcp to check that agent-notify is connected. The setup command downloads and loads the voice model, then opens a real test notification. Its generated audio is cached for later runs.

Upgrading from the earlier tts.speak tool:

codex mcp remove tts
codex mcp add agent-notify -- "$(pwd)/.venv/bin/tts-mcp"

Related MCP server: Claude Code Notification Hooks

Turn TTS on or off

Use the TTS ON / TTS OFF button in any notification window. Your choice is saved and applies to future messages; muted messages remain visible so you can turn speech back on. Turning TTS off also stops the message currently playing, and the muted window remains open for 15 seconds. A small bar at the bottom shows the remaining display time. Use the pause button beside the bar to keep a notification open, then resume the remaining countdown or close it manually.

You can also use the terminal:

uv run tts-config off
uv run tts-config on
uv run tts-config status

Try it

uv run tts-notify \
  '{"type":"agent-turn-complete","last-assistant-message":"TTS is ready."}'

Test

uv run pytest

Optional settings

Set these environment variables when registering the server with codex mcp add ... --env NAME=VALUE:

• TTS_MCP_MODEL — Coqui model name; overrides the model saved from Options

• TTS_MCP_SPEAKER — speaker ID for a multi-speaker model

• TTS_MCP_OUTPUT_DIR — directory for cached WAV files

• TTS_MCP_OVERLAY=off — play audio without the overlay

• TTS_MCP_REPLY_COMMAND — optional local LLM command used to draft replies

• TTS_MCP_REPLY_TIMEOUT — local reply command timeout in seconds (default 120)

• TTS_MCP_REDUCE_MOTION=on — replace urgent blinking with a solid alert

• TTS_MCP_PROVIDER — local (default) or openrouter

• OPENROUTER_API_KEY — required only for OpenRouter synthesis

• TTS_MCP_OPENROUTER_MODEL — defaults to deepgram/flux-tts:free

• TTS_MCP_OPENROUTER_VOICE — defaults to flux-bree-en

• TTS_MCP_OPENROUTER_FALLBACK=0 — fail instead of using local Coqui

The default model is tts_models/en/jenny/jenny. Audio continues to work when no graphical display is available.

Optional OpenRouter TTS

Local Coqui remains the default. To use Deepgram Flux TTS through OpenRouter, set these environment variables on the MCP server:

TTS_MCP_PROVIDER=openrouter
OPENROUTER_API_KEY=...
TTS_MCP_OPENROUTER_MODEL=deepgram/flux-tts:free
TTS_MCP_OPENROUTER_VOICE=flux-bree-en

The remote provider uses OpenRouter's speech endpoint and keeps the generated WAV in the existing audio cache. Set TTS_MCP_OPENROUTER_FALLBACK=0 to disable the default local-Coqui fallback when OpenRouter is unavailable.