AgentVibes

AgentVibes uses a multi-provider TTS (Text-to-Speech) architecture that allows for seamless switching between different speech services. The system uses a Router + Provider Implementation pattern to abstract provider-specific details behind a unified interface. This enables runtime provider switching, automatic voice mapping, and plugin extensibility without changing application configuration.

Supported Providers by Platform

Linux/macOS:

• Piper TTS (play-tts-piper.sh): Local neural voices.
• macOS Say (play-tts-macos.sh): Native macOS TTS.
• SSH Remote (play-tts-ssh-remote.sh): Forwards TTS to a remote host via SSH.
• Soprano (play-tts-soprano.sh): Gradio API endpoint for custom models.
• Termux SSH (play-tts-termux-ssh.sh): Android device via Termux.
• AgentVibes Receiver (play-tts-agentvibes-receiver.sh): Proxy for voiceless connections.

Windows:

• Windows SAPI (play-tts-sapi.ps1): Native Windows Speech API.
• Windows Piper (play-tts-windows-piper.ps1): Local neural voices on Windows.
• Windows Soprano (play-tts-soprano.ps1): Gradio API on Windows.

AgentVibes employs a multi-layered defense-in-depth strategy to secure file path operations, particularly for the custom music upload feature. The system is designed to prevent path traversal, symlink/hardlink attacks, and information disclosure.

Key security layers include:

1. Type Validation: Ensures input is a non-empty string.
2. Path Resolution: Uses path.resolve() to convert paths to absolute canonical form, eliminating ../, ., and symbolic link components.
3. Home Directory Boundary Check: Verifies the resolved path starts with the user's home directory (homeDir + path.sep) to prevent escaping to parent directories.
4. File Existence & Type Verification: Confirms the path exists and is a regular file (using stats.isFile()), rejecting directories, devices, or sockets.
5. Ownership Verification: Uses stats.uid === process.getuid() to ensure the file is owned by the current user, which is a critical defense against malicious symlinks.
6. Secure Storage: Files are copied to a restricted directory with controlled naming and preserved permissions.

AgentVibes relies on a specific protocol injected via the .claude/hooks/startup.sh file to ensure the AI communicates verbally. The AI is instructed to execute the play-tts.sh script at two critical points:

1. Acknowledgment: At the start of a task. The AI generates a unique acknowledgment in its current personality/sentiment style and executes: Bash: .claude/hooks/play-tts.sh "[action]".
2. Completion: At the end of a task. The AI generates a unique completion message and executes: Bash: .claude/hooks/play-tts.sh "[result + key details]".

This protocol allows the AI to verbally confirm it has understood a command and report the outcome, creating a seamless conversational experience.

# .claude/hooks/startup.sh content injected into Claude:
**CRITICAL: You MUST execute TTS at TWO points for EVERY user interaction:**

1. **Acknowledgment** - Start of task: `Bash: .claude/hooks/play-tts.sh "[action]"`
2. **Completion** - End of task: `Bash: .claude/hooks/play-tts.sh "[result + key details]"`

The ProviderRecord is the canonical data structure for a voice provider in src/services/provider-catalog.js. Each provider follows one of four voiceModel patterns:

• static: A fixed list of IDs (e.g., kokoro).
• discovered: Voices are found on disk or via system calls; the catalog provides the validation rule, but the caller must inject the installedVoices list (e.g., piper, macos, windows-sapi).
• single: Only one valid voice exists (e.g., soprano).
• name-to-id: Maps names to IDs or allows raw ID passthrough (e.g., elevenlabs).

Schema Definition:

ProviderRecord = {
  id:           'kokoro',                      // canonical id (matches SUPPORTED_PROVIDERS)
  engineId:     'kokoro',                      // resolver ENGINES value ('sapi' for windows-sapi)
  aliases:      [],                            // e.g. windows-sapi: ['sapi']; windows-piper: ['piper' on win]
  displayName:  'Kokoro TTS',
  voiceModel:   'static' | 'discovered' | 'single' | 'name-to-id',
  voices:       [...ids] | [{name,id,gender,lang,desc}] | null,   // null when discovered
  defaultVoice: 'af_heart',
  runtime:      { unix: 'play-tts-kokoro.sh', windows: 'play-tts-kokoro.ps1', darwinOnly: false },
  requires:     'api-key' | 'pip' | 'builtin' | 'exe',
}

AgentVibes uses two distinct layers to manage audio output. Understanding the difference is critical for debugging configuration vs. playback issues:

1. Provider Catalog (Inventory): Answers "WHAT exists to speak with?". It manages the inventory of available voices, default settings, validation rules, and platform-specific runtime scripts. It is used during configuration time (e.g., when running switch, set_provider, or set_voice) to reject typos and validate membership.

2. Utterance Resolver (Routing): Answers "HOW is this utterance spoken?". It manages the precedence and routing of voice, engine, transport, mute, and volume settings. It is used during playback time (every utterance).

Key Relationship: The Catalog sits upstream of the Resolver. The Catalog is strict (rejecting invalid voices at config time), while the Resolver is lenient (using regex heuristics to attempt routing even if a voice is unknown, ensuring the system degrades gracefully rather than bricking).