NotificationStopFailure· rate_limit

Desktop notification on rate limit

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.

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

Providers & tags

Claude Code

#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()));
}