hiro-voice-sounds

Hiro Voice Sounds for Claude Code

Give your Claude Code sessions a voice. This plugin plays Hiro-themed voice lines when Claude Code events fire — session starts, prompt acknowledgments, task completions, and permission requests.

Each event randomly picks from multiple voice clips with no-repeat logic, so it never feels repetitive.

Installation

1. Clone the repo

git clone https://github.com/OnjoujiToki/claude-hiro-voices.git
cd claude-hiro-voices
chmod +x scripts/play-sound.sh scripts/hiro-voice-sounds

2. Add hooks to your Claude Code settings

Open ~/.claude/settings.json and add the hooks section (adjust the path to where you cloned the repo):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash '/path/to/claude-hiro-voices/scripts/play-sound.sh' session-start"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash '/path/to/claude-hiro-voices/scripts/play-sound.sh' task-acknowledge"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash '/path/to/claude-hiro-voices/scripts/play-sound.sh' task-complete"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash '/path/to/claude-hiro-voices/scripts/play-sound.sh' permission"
          }
        ]
      }
    ]
  }
}

Replace /path/to/claude-hiro-voices with the actual path where you cloned the repo.

That's it — hooks are picked up immediately, no restart needed.

Sound Events

Claude Code Event	Category	What Plays
SessionStart	session-start	Hiro intro voice lines
UserPromptSubmit	task-acknowledge	Hiro acknowledgment voice lines
Stop	task-complete	Hiro completion voice lines
Notification	permission	Hiro permission voice lines

An error category is also included for manual testing or future hook wiring.

Configuration

Edit config.json to adjust settings:

{
  "volume": 0.6,
  "theme": "hiro-voice",
  "enabled_events": {
    "session-start": true,
    "task-acknowledge": true,
    "task-complete": true,
    "error": true,
    "permission": true
  }
}

• volume — playback volume from 0.0 to 1.0
• theme — set to "hiro-voice" for the bundled clips
• enabled_events — toggle individual events on/off

CLI

A small management CLI is included:

./scripts/hiro-voice-sounds status          # Show theme, volume, and file counts
./scripts/hiro-voice-sounds volume 0.4      # Set volume
./scripts/hiro-voice-sounds test task-complete  # Play a test sound
./scripts/hiro-voice-sounds paths           # Show resolved plugin paths

Add Your Own Sounds

Drop .mp3, .wav, .ogg, or .aiff files into any category folder:

sounds/session-start/
sounds/task-acknowledge/
sounds/task-complete/
sounds/error/
sounds/permission/

Custom files in a folder replace the defaults for that category. The plugin randomly picks one each time with no-repeat logic.

Fallback Sounds (macOS)

If a category folder has no custom audio files, the plugin falls back to macOS system sounds:

Category	System Sound
session-start	Hero.aiff
task-acknowledge	Tink.aiff
task-complete	Glass.aiff
error	Sosumi.aiff
permission	Morse.aiff

Platform Support

• macOS — uses afplay (built-in)
• Linux — uses pw-play (PipeWire), paplay (PulseAudio), or ffplay (FFmpeg)
• Falls back to terminal bell if no player is found

License

MIT