Rupor

When silence is not an option

Rupor is a CLI tool that brings voice notifications to your terminal. Never miss important build results, test failures, or long-running command completions again.

Features

• Voice notifications for terminal commands using OpenAI's TTS
• Smart command wrapper (rupor run) that announces start, success, and failure with contextual information
• Profile-based configuration for different notification scenarios
• Audio caching to avoid redundant TTS API calls
• Environment variable injection for custom notification contexts
• Layered architecture with constructor-based dependency injection and testable use cases

Installation

npm install -g rupor

Platform notes:

• Linux: supported
• macOS: expected to work if play or ffplay is installed and available in PATH
• Windows: expected to work if ffplay or another compatible play command is available in PATH, but this setup is not documented or tested in this repository

Quick Start

Say a message

rupor say "Build completed successfully"
rupor say "Test failed" --voice nova

Run a profile

HOOK_STDIN='{"hook_event_name":"Notification","message":"Build finished"}' rupor notify claude

Wrap commands with voice notifications

Wrap any command to get voice notifications on start, success, and failure:

rupor run npm test
rupor run npm run build
rupor run -t npm run dev  # or --preserve-tty

The wrapper intelligently analyzes command output to provide meaningful notifications:

• For test failures: counts failed tests and identifies the first failing test
• For build errors: identifies compilation errors and missing dependencies
• For general failures: extracts relevant error messages

List available voices

rupor voice list
rupor voice list --json

List configured profiles

rupor profile list
rupor profile list --json

Configuration

Configuration is stored at ~/.config/rupor/config.yml:

openai:
  apiKey: "sk-..."
  completionModel: gpt-4o-mini
  voice: alloy
  ttsModel: tts-1

profiles:
  run:
    temperature: 0.8
    voice: nova

  claude:
    exposed-envs:
      HOOK_STDIN:
        required: true
    prompt: |
      Interpret the Claude Code hook payload from HOOK_STDIN and turn it into a short voice message.

See config.example.yaml for complete examples.

Claude Hooks

If you use Claude Code, rupor can speak notifications from Claude hooks. A working example in ~/.claude/settings.json looks like this:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "HOOK_STDIN=$(cat) rupor notify claude"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "HOOK_STDIN=$(cat) rupor notify claude"
          }
        ]
      }
    ]
  }
}

rupor notify claude expects the hook payload in HOOK_STDIN, then uses the claude profile from your rupor config to generate the spoken message.

Architecture

The codebase is organized into domain, application, infrastructure, presentation, and di.

• application owns use cases, errors, and external service ports
• domain holds entities and domain-facing services
• infrastructure implements OpenAI, audio playback, config loading, and cache persistence
• presentation maps CLI commands to use cases and keeps process/env concerns at the boundary

Cache

Audio files are cached in ~/.cache/rupor/tts/ to avoid regenerating identical notifications.

Clear the cache with:

rupor clear-cache

External Requirements

• Node.js 18+
• An OpenAI API key in ~/.config/rupor/config.yml or config.yaml
• One of these audio players installed: play from SoX ffplay from FFmpeg

Without play or ffplay, the CLI can still generate speech, but it will not be able to play audio automatically.

Audio playback implementation notes:

• the current implementation tries play "<file>" first
• if that fails, it falls back to ffplay -autoexit -nodisp "<file>"
• because of that, cross-platform support mostly depends on whether one of those commands exists on your machine

Use Cases

• Long-running tests: Know immediately when your test suite finishes
• Claude Code hooks: Voice notifications for Claude Code events
• Custom workflows: Create profiles for any notification scenario

License

WTFPL