opencode-smart-voice-notify

v1.2.4

Published

10 hours ago

Smart voice notification plugin for OpenCode with multiple TTS engines (ElevenLabs, Edge TTS, Windows SAPI), AI-generated dynamic messages, and intelligent reminder system

0High
0Medium
0Low

masurii

opencode opencode-plugins plugin notification tts text-to-speech elevenlabs edge-tts sapi voice alert smart ai ai-generated ollama local-ai

OpenCode Smart Voice Notify

Disclaimer: This project is not built by the OpenCode team and is not affiliated with OpenCode in any way. It is an independent community plugin.

A smart voice notification plugin for OpenCode with multiple TTS engines and an intelligent reminder system.

Features

Smart TTS Engine Selection

The plugin automatically tries multiple TTS engines in order, falling back if one fails:

ElevenLabs (Online) - High-quality, anime-like voices with natural expression
Edge TTS (Free) - Microsoft's neural voices, native Node.js implementation (no Python required)
Windows SAPI (Offline) - Built-in Windows speech synthesis
Local Sound Files (Fallback) - Plays bundled MP3 files if all TTS fails

Smart Notification System

Sound-first mode: Play a sound immediately, then speak a TTS reminder if user doesn't respond
TTS-first mode: Speak immediately using TTS
Both mode: Play sound AND speak TTS at the same time
Sound-only mode: Just play sounds, no TTS

Intelligent Reminders

Delayed TTS reminders if user doesn't respond within configurable time
Follow-up reminders with exponential backoff
Automatic cancellation when user responds
Per-notification type delays (permission requests are more urgent)
Smart Quota Handling: Automatically falls back to free Edge TTS if ElevenLabs quota is exceeded
Permission Batching: Multiple simultaneous permission requests are batched into a single notification (e.g., "5 permission requests require your attention")
Question Tool Support (SDK v1.1.7+): Notifies when the agent asks questions and needs user input

AI-Generated Messages

Dynamic notifications: Use a local AI to generate unique, contextual messages instead of preset static ones
OpenAI-compatible: Works with Ollama, LM Studio, LocalAI, vLLM, llama.cpp, Jan.ai, or any OpenAI-compatible endpoint
User-hosted: You provide your own AI endpoint - no cloud API keys required
Custom prompts: Configure prompts per notification type for full control over AI personality
Smart fallback: Automatically falls back to static messages if AI is unavailable

System Integration

Native Edge TTS: No external dependencies (Python/pip) required
Wake monitor from sleep before notifying
Auto-boost volume if too low
TUI toast notifications
Cross-platform support (Windows, macOS, Linux)

Installation

Option 1: From npm/Bun (Recommended)

Add to your OpenCode config file (~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-smart-voice-notify@latest"]
}

Note: OpenCode will automatically install the plugin using your system's package manager (npm or bun).

Option 2: From GitHub

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["github:MasuRii/opencode-smart-voice-notify"]
}

Option 3: Local Development

Clone the repository:

git clone https://github.com/MasuRii/opencode-smart-voice-notify.git

Reference the local path in your config:

{
  "plugin": ["file:///path/to/opencode-smart-voice-notify"]
}

Configuration

Automatic Setup

When you first run OpenCode with this plugin installed, it will automatically create:

~/.config/opencode/smart-voice-notify.jsonc - A comprehensive configuration file with all available options fully documented.
~/.config/opencode/assets/*.mp3 - Bundled notification sound files.
~/.config/opencode/logs/ - Debug log folder (created when debug logging is enabled).

The auto-generated configuration includes all advanced settings, message arrays, and engine options, so you don't have to refer back to the documentation for available settings.

Manual Configuration

If you prefer to create the config manually, add a smart-voice-notify.jsonc file in your OpenCode config directory (~/.config/opencode/):

{
    // ============================================================
    // OpenCode Smart Voice Notify - Quick Start Configuration
    // ============================================================
    // For ALL available options, see example.config.jsonc in the plugin.
    // The plugin auto-creates a comprehensive config on first run.
    // ============================================================

    // Master switch to enable/disable the plugin without uninstalling
    "enabled": true,

    // Notification mode: 'sound-first', 'tts-first', 'both', 'sound-only'
    "notificationMode": "sound-first",
    
    // TTS engine: 'elevenlabs', 'edge', 'sapi'
    "ttsEngine": "elevenlabs",
    "enableTTS": true,
    
    // ElevenLabs settings (get API key from https://elevenlabs.io/app/settings/api-keys)
    "elevenLabsApiKey": "YOUR_API_KEY_HERE",
    "elevenLabsVoiceId": "cgSgspJ2msm6clMCkdW9",  // Jessica - Playful, Bright
    
    // Edge TTS settings (free, no API key required)
    "edgeVoice": "en-US-AnaNeural",
    "edgePitch": "+50Hz",
    "edgeRate": "+10%",
    
    // TTS reminder settings
    "enableTTSReminder": true,
    "ttsReminderDelaySeconds": 30,
    "enableFollowUpReminders": true,
    "maxFollowUpReminders": 3,
    
    // AI-generated messages (optional - requires local AI server)
    "enableAIMessages": false,
    "aiEndpoint": "http://localhost:11434/v1",
    "aiModel": "llama3",
    "aiApiKey": "",
    "aiFallbackToStatic": true,
    
    // General settings
    "wakeMonitor": true,
    "forceVolume": true,
    "volumeThreshold": 50,
    "enableToast": true,
    "enableSound": true,
    "debugLog": false
}

For the complete configuration with all TTS engine settings, message arrays, AI prompts, and advanced options, see example.config.jsonc in the plugin directory.

AI Message Generation (Optional)

If you want dynamic, AI-generated notification messages instead of preset ones, you can connect to a local AI server:

Install a local AI server (e.g., Ollama):

# Install Ollama and pull a model
ollama pull llama3

Enable AI messages in your config:

{
  "enableAIMessages": true,
  "aiEndpoint": "http://localhost:11434/v1",
  "aiModel": "llama3",
  "aiApiKey": "",
  "aiFallbackToStatic": true
}

The AI will generate unique messages for each notification, which are then spoken by your TTS engine.

Supported AI Servers: | Server | Default Endpoint | API Key | |--------|-----------------|---------| | Ollama | http://localhost:11434/v1 | Not needed | | LM Studio | http://localhost:1234/v1 | Not needed | | LocalAI | http://localhost:8080/v1 | Not needed | | vLLM | http://localhost:8000/v1 | Use "EMPTY" | | Jan.ai | http://localhost:1337/v1 | Required |

Requirements

For ElevenLabs TTS

ElevenLabs API key (free tier: 10,000 characters/month)
Internet connection

For Edge TTS

Internet connection (No external dependencies required)

For Windows SAPI

Windows OS (uses built-in System.Speech)

For Sound Playback

Windows: Built-in (uses Windows Media Player)
macOS: Built-in (afplay)
Linux: paplay or aplay

Events Handled

| Event | Action | |-------|--------| | session.idle | Agent finished working - notify user | | permission.asked | Permission request (SDK v1.1.1+) - alert user | | permission.updated | Permission request (SDK v1.0.x) - alert user | | permission.replied | User responded - cancel pending reminders | | question.asked | Agent asks question (SDK v1.1.7+) - notify user | | question.replied | User answered question - cancel pending reminders | | question.rejected | User dismissed question - cancel pending reminders | | message.updated | New user message - cancel pending reminders | | session.created | New session - reset state |

Note: The plugin supports OpenCode SDK v1.0.x, v1.1.x, and v1.1.7+ for backward compatibility.

Development

To develop on this plugin locally: