tonton

Play a notification sound from your terminal. Zero dependencies. ~15KB.

Perfect for getting pinged when AI coding tools (Claude Code, Codex, etc.) finish a task — or need your attention.

Quick Start

npx tonton-cli --setup

That's it. Claude Code will now play:

• A done sound when the agent finishes
• An input sound when the agent needs you

Install

npm install -g tonton-cli

Or use without installing — npx tonton-cli works everywhere.

Two Sounds

| Command | When | macOS | Cross-platform | |---------|------|-------|---------------| | tonton --done | Agent finished | Glass | Descending chime | | tonton --input | Agent needs you | Funk | Ascending chime |

tonton --done     # hear the "finished" sound
tonton --input    # hear the "need attention" sound
tonton            # default notification sound

Use with AI CLI Tools

Claude Code — automatic setup

npx tonton-cli --setup

This adds hooks to ~/.claude/settings.json so Claude Code plays distinct sounds when done vs. needing input. Run once, works forever.

Updating? Just run --setup again — it removes old hooks before adding new ones, so there's no doubling:

npm update -g tonton-cli
tonton --setup

To remove: npx tonton-cli --remove

Claude Code — manual setup

Add to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "npx tonton-cli --done" }] }
    ],
    "PermissionRequest": [
      { "matcher": "", "hooks": [{ "type": "command", "command": "npx tonton-cli --input" }] }
    ]
  }
}

Codex CLI

codex "fix the bug" ; npx tonton-cli --done

Any command

npm test ; npx tonton-cli --done
long-running-task ; npx tonton-cli

Shell alias

# Add to ~/.zshrc or ~/.bashrc
notify() { "$@"; npx tonton-cli --done; }

# Then use:
notify npm test
notify codex "refactor this"

More Options

# Pick a specific sound (macOS system sounds)
tonton --sound Glass
tonton --sound Hero

# Adjust volume (macOS only)
tonton --volume 0.5

# List available sounds
tonton --list

Programmatic API

import { play, listSounds } from 'tonton-cli';

await play();                          // default sound
await play({ sound: 'done' });         // completion sound
await play({ sound: 'input' });        // attention sound
await play({ sound: 'Glass' });        // macOS system sound
await play({ volume: 0.5 });           // half volume (macOS)

const sounds = listSounds();           // available sound names

Cross-Platform

| Platform | Player | Sounds | |----------|--------|--------| | macOS | afplay (built-in) | 14 system sounds + synthesized chime | | Linux | paplay / aplay / ffplay | Freedesktop sounds + synthesized chime | | Windows | PowerShell SoundPlayer | Windows Media sounds + synthesized chime |

Falls back to a synthesized two-tone chime, then terminal bell — always plays something.

Always exits 0. A notification sound will never break your scripts, hooks, or CI.

License

MIT