HookStackGitHub
Back to catalogue
NotificationStopStopWhen the agent finishes its task· non-blocking

System sound on task completion

A satisfying chime the moment Claude finishes

Plays a completion sound (Hero.aiff on macOS, paplay on Linux, PowerShell beep on Windows) when the agent stops. Instant audio feedback without TTS, no voice engine required.

What does the System sound on task completion hook do?

System sound on task completion is a Claude Code Stop hook. It fires automatically at that lifecycle event — outside the model, so it can't be skipped or forgotten. A satisfying chime the moment Claude finishes.

Use cases

  • Audio feedback when a long task finishes
  • Minimal-distraction alternative to TTS
  • Complement stop-tts-completion with a lighter signal

Tags

#stop#sound#audio#completion#cross-platform

settings.json fragment

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/stop-sound.mjs",
            "type": "command"
          }
        ],
        "matcher": ""
      }
    ]
  }
}

Script · .claude/hooks/stop-sound.mjs

#!/usr/bin/env node
// Joue un son de completion quand Claude termine une tâche (Stop)
import { execSync } from 'child_process';
import { fileURLToPath } from 'url';

function defaultExec(cmd) {
  execSync(cmd, { timeout: 5_000, stdio: 'ignore', shell: true });
}

export function run({ exec = defaultExec, platform = process.platform } = {}) {
  try {
    if (platform === 'darwin') {
      exec('afplay /System/Library/Sounds/Hero.aiff');
      exec('osascript -e \'display notification "Claude has finished working" with title "Claude Code"\'');
    } else if (platform === 'linux') {
      exec('paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || aplay /usr/share/sounds/alsa/Front_Center.wav 2>/dev/null || true');
    } else if (platform === 'win32') {
      exec('powershell -c "[console]::beep(880, 400)"');
    }
  } catch {
    // Son absent ou erreur — non bloquant
  }
  return null;
}

/* v8 ignore next 3 */
if (process.argv[1] === fileURLToPath(import.meta.url)) {
  run();
}