HookStackGitHub
Back to catalogue
NotificationStopFailure· rate_limit

Desktop notification on rate limit

Get pinged when a rate limit pauses Claude

Fires a desktop notification via a terminal escape sequence when Claude Code hits an API rate limit. Lets you step away and come back when the quota resets without polling the terminal.

What does the Desktop notification on rate limit hook do?

Desktop notification on rate limit is a Claude Code StopFailure hook matching rate_limit. It fires automatically at that lifecycle event — outside the model, so it can't be skipped or forgotten. Get pinged when a rate limit pauses Claude.

Use cases

  • Get a desktop ping when Claude Code is paused by a rate limit
  • Avoid missing rate-limit pauses during long autonomous sessions
  • Works in iTerm2, WezTerm, Windows Terminal and other OSC-9 compatible terminals

Tags

#rate-limit#notification#alert#desktop#stop-failure

settings.json fragment

{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/stop-failure-rate-limit-alert.mjs",
            "type": "command"
          }
        ],
        "matcher": "rate_limit"
      }
    ]
  }
}

Script · .claude/hooks/stop-failure-rate-limit-alert.mjs

#!/usr/bin/env node
// StopFailure (rate_limit) : déclenche une notification bureau via OSC-9
import { fileURLToPath } from 'url';

export function run() {
  const seq = '\x1b]9;Claude Code — rate limit hit, paused\x07';
  return { terminalSequence: seq };
}

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