xxdesmus-claude-alertr

claude-alertr

Get notified when Claude Code is waiting for your input.

When Claude hits a permission prompt or asks a question, claude-alertr waits a configurable delay (default: 60s) and then sends you an alert via Slack, Discord, or email — including what Claude is waiting on and which machine it's running on.

Disclaimer: This is an independent, community-built tool. It is not affiliated with, endorsed by, or supported by Anthropic. Use of Claude Code is subject to Anthropic's Terms of Service.

How It Works

Two local shell hooks monitor Claude Code. When Claude is blocked waiting for you, a background timer starts. If you don't respond in time, the hook POSTs to a Cloudflare Worker you deploy, which relays the alert to your notification channels. When you respond, the timer is automatically cancelled.

Claude Code (local)                      Cloudflare Worker (relay)
┌──────────────┐                        ┌──────────────┐
│ Hook fires   │── delay ── curl POST ──│ /alert       │──▶ Slack / Discord webhook
│ on prompt    │                        │              │──▶ Email via Resend
│ Hook cancels │                        └──────────────┘
│ on response  │
└──────────────┘

Quick Start

1. Deploy the Worker

git clone https://github.com/xxdesmus/claude-alertr.git
cd claude-alertr
npm install
npx wrangler login   # if not already authenticated
npm run deploy

Note the Worker URL printed (e.g., https://claude-alertr.<you>.workers.dev).

2. Set Worker secrets

# Required — protects your Worker from unauthorized use
wrangler secret put AUTH_TOKEN

# At least one notification channel:
wrangler secret put WEBHOOK_URL          # Slack or Discord webhook URL
# — or —
wrangler secret put RESEND_API_KEY       # Email via Resend
wrangler secret put ALERT_EMAIL_TO       # Recipient email address
# — or —
wrangler secret put SHOUTRRR_URLS        # Shoutrrr URL(s) — see Notification Channels

3. Install the plugin

In Claude Code:

/plugin marketplace add xxdesmus/claude-alertr
/plugin install claude-alertr@xxdesmus-claude-alertr
/claude-alertr:setup

The setup wizard walks you through entering your Worker URL, auth token, and alert delay — then tests the connection. Hooks are auto-registered.

Tip: Visit https://<your-worker>.workers.dev/setup for a browser-based setup wizard as an alternative.

4. Test it

curl -X POST \
  -H "Authorization: Bearer <your-token>" \
  https://<your-worker>.workers.dev/test

You should receive a notification within seconds.

Configuration

Config lives at ~/.claude-alertr/config:

Setting	Description	Default
CLAUDE_ALERTR_URL	Your deployed Worker URL	(required)
CLAUDE_ALERTR_TOKEN	Auth token (must match Worker's AUTH_TOKEN secret)	(required)
CLAUDE_ALERTR_DELAY	Seconds to wait before alerting (15–300)	60

Notification Channels

All channels can be active simultaneously.

Webhook

Set WEBHOOK_URL on the Worker. Alerts are sent as JSON with a text field compatible with Slack and Discord incoming webhooks. Example message:

[macbook-pro] Claude Code is waiting for your input (permission_prompt)
Pull latest changes from GitHub: git pull

Email (via Resend)

Set RESEND_API_KEY and ALERT_EMAIL_TO on the Worker. Optionally set ALERT_EMAIL_FROM (defaults to [email protected]). Sends a styled HTML email with type, details, project, host, and session info.

Shoutrrr (multi-service)

Set SHOUTRRR_URLS on the Worker with one or more Shoutrrr-compatible URLs (space or newline separated). This enables 7 additional notification services with a single secret:

Service	URL format
Slack	slack://token-a/token-b/token-c
Discord	discord://webhook-token@webhook-id
Telegram	telegram://bot-id:bot-token@telegram?chats=@channel,chat-id
Ntfy	ntfy://[user:pass@]ntfy.sh/topic
Pushover	pushover://shoutrrr:api-token@user-key
Gotify	gotify://host[:port]/app-token
Generic webhook	generic://host[:port]/path

Example with multiple services:

wrangler secret put SHOUTRRR_URLS
# Enter: slack://T00/B00/XXX ntfy://ntfy.sh/my-alerts

Shoutrrr URLs work alongside WEBHOOK_URL and email — you can mix and match.

Note: Cloudflare Workers cannot reliably reach services that are also behind Cloudflare (proxied DNS or Cloudflare Tunnel). If a Shoutrrr target (e.g., a self-hosted Gotify or Ntfy instance) is proxied through Cloudflare, the Worker's fetch() may fail with Cloudflare error 1003. Use an unproxied DNS record for the target or route through a non-Cloudflare endpoint instead.

Alert Payload

The hook sends a JSON payload to the Worker's /alert endpoint: