claude-nag

claude-nag

Progressive notification escalation for Claude Code. Starts quiet, gets louder.

The Problem

You walk away from your computer. Claude is waiting for input. You don't know.

The Solution

When Claude needs your attention, claude-nag pings every 60 seconds, getting progressively louder:

Time	Volume
1 min	15%
2 min	30%
3 min	50%
4 min	70%
5 min	85%
6 min	100%

After 6 pings it stops. When you respond, it stops immediately.

Installation

brew install terminal-notifier
/plugin marketplace add jdx/claude-nag
/plugin install claude-nag@jdx-claude-nag

Then restart Claude Code.

Configuration

Edit ~/.config/claude-nag/config.json:

{
  "sound": "/System/Library/Sounds/Ping.aiff",
  "tiers": [
    [60, 15, "Claude is waiting..."],
    [60, 30, "Claude is waiting..."],
    [60, 50, "Claude needs your attention"],
    [60, 70, "Claude needs your attention"],
    [60, 85, "Hey! Claude needs you!"],
    [60, 100, "CLAUDE NEEDS YOUR INPUT!"]
  ],
  "max_notifications": 6
}

Each tier is [delay_seconds, volume_percent, notification_message].

Custom Sounds

Use any audio file macOS can play:

{
  "sound": "/path/to/your/sound.mp3"
}

Built-in macOS sounds are in /System/Library/Sounds/:

• Ping.aiff (default)
• Glass.aiff
• Submarine.aiff
• Hero.aiff
• etc.

How It Works

1. Claude Code's Notification hook fires when Claude needs user input
2. start-nag.sh launches the nag daemon in background
3. Daemon waits through escalating tiers, playing sounds + showing notifications
4. When you interact with Claude, PreToolUse hook fires
5. stop-nag.sh kills the daemon

Platform Support

• macOS: Full support (afplay + terminal-notifier)
• Linux: Should work (paplay + notify-send) but untested

License

MIT