claudestat-alert-slack

Slack alerting for @statforge/claudestat — sends quota, loop, and cost alerts to Slack via Incoming Webhook.

Install

npm install -g @statforge/claudestat-alert-slack

Quick start

# 1. Create a Slack Incoming Webhook: https://api.slack.com/messaging/webhooks
# 2. Ensure claudestat daemon is running
claudestat start

# 3. Start the alerter
claudestat-alert-slack --webhook-url https://hooks.slack.com/services/...

Or use an env var:

export CLAUDESTAT_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
claudestat-alert-slack

Alerts (4)

| Alert | Condition | Message | |---|---|---| | Quota cycle high | computeQuota().cyclePct >= 85 | ⚠️ Quota Cycle at {pct}%+ with token usage and reset countdown | | Loops detected | Latest session has loops_detected > 0 | 🔄 Loops Detected with session ID, loop count, efficiency | | High-cost session | Latest session cost ≥ --session-cost-threshold (default $5) | 💰 High-Cost Session with session ID and cost | | Shutdown | SIGTERM/SIGINT received | claudestat-alert-slack stopped with uptime |

CLI flags

claudestat-alert-slack [options]

Required:
  -w, --webhook-url <url>             Slack Incoming Webhook URL

Options:
  -i, --interval <seconds>            Poll interval (default: 60)
  -d, --dedup-minutes <number>        Dedup window (default: 30, 0 = disabled)
  -s, --session-cost-threshold <usd>  Cost alert threshold (default: 5)
  --state-file <path>                 State file (default: ~/.claudestat-slack-state.json)
  --dry-run                           Print alerts to stdout (no Slack POST)
  --throw-on-no-daemon                Exit 1 if daemon unreachable on first poll
  --quiet-shutdown                    No shutdown notification
  -v, --version                       Show version
  -h, --help                          Show help

Dedup

Alerts are deduplicated within a configurable window (default 30 min). State persists to ~/.claudestat-slack-state.json across restarts, so you won't get spammed with the same alert after a process restart.

Use --dedup-minutes 0 to disable dedup (useful for testing with --dry-run).

Dry run

claudestat-alert-slack --webhook-url https://hooks.slack.com/test --dry-run --interval 10 --dedup-minutes 0

Prints formatted Slack messages to stdout without sending anything.

Requirements

• Node.js >= 22 (for node:sqlite in claudestat)
• @statforge/claudestat daemon running (claudestat start)
• Slack Incoming Webhook URL

License

MIT