Adapted from the black-candle-technologies/usage-notifier repository docs.
An Uptime Kuma-style dashboard that monitors subscription usage limits — OpenAI, Anthropic, Z.ai, OpenCode Go, and MiniMax — and sends deduplicated Discord alerts when a quota runs low. Python standard library only, no dependencies.
Every poll interval the monitor asks each provider's usage API how much quota is left, stores the result in a local SQLite history, and evaluates alert rules:
The web dashboard shows every monitor as a status card with a usage bar, reset countdown, check history sparkbars, a detail view with full history, and a recent-alerts feed, in the visual language of Uptime Kuma.
| Provider | What is monitored | Key needed |
|---|---|---|
| OpenAI | Monthly API spend vs configured USD budget | Org Admin key (sk-admin-…); regular keys get 403 |
| Anthropic | Org spend limits vs period spend | Org Admin key (sk-ant-admin-…); regular keys get 403 |
| Z.ai | Coding Plan quota windows | z.ai API key (unofficial console endpoint) |
| OpenCode Go | Go plan usage — rolling 5h / weekly / monthly in USD | Go subscription key (not a Zen key) |
| MiniMax | M Plan remaining quota | M Plan Subscription Key (not the pay-as-you-go key) |
A monitor without a key shows as "not configured"; nothing is polled and no alerts fire.
python3 -m usage_notifier init # writes an example config.json
# add API keys, then:
python3 -m usage_notifier validate # checks config + key presence
python3 -m usage_notifier check --no-notify # one poll cycle, no Discord
python3 -m usage_notifier serve # poll loop + dashboard on :8420
Open http://127.0.0.1:8420.
Environment variables (preferred) or secrets.json next to config.json (values below are placeholders):
export USAGE_NOTIFIER_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…"
export USAGE_NOTIFIER_OPENAI_API_KEY=<your-openai-admin-key>
export USAGE_NOTIFIER_ANTHROPIC_API_KEY=<your-anthropic-admin-key>
export USAGE_NOTIFIER_ZAI_API_KEY=<your-zai-key>
export USAGE_NOTIFIER_OPENCODE_API_KEY=<your-opencode-key>
export USAGE_NOTIFIER_MINIMAX_API_KEY=<your-minimax-key>
See .env.example. secrets.json uses lowercase keys (openai_api_key, discord_webhook_url, …).
config.json (see config.example.json):
monitors: list of {id, enabled, label?, budget?} — budget is the monthly USD cap for the OpenAI spend monitorpoll_interval_minutes (default 15), warning_remaining_percent (25), critical_remaining_percent (10)alert_thresholds_remaining_percent (default [25, 10, 0])web_bind / web_port (default 127.0.0.1:8420), history_days (30)discord_username, discord_avatar_url, discord_critical_mention (<@user> / <@&role> on critical alerts)State lives under ~/.local/state/usage-notifier (USAGE_NOTIFIER_HOME overrides): history.sqlite, state.json, logs.
docs/usage-notifier.service is a systemd unit template. The dashboard binds loopback by default; front it with Caddy (or similar) for TLS:
usage.internal.blackcandletech.com {
reverse_proxy 127.0.0.1:8420
}
POST /api/check (manual "Check now") only answers on loopback — through a reverse proxy it returns 403, which is intentional.
docs/ubuntu-24.04.md covers systemd user-service deployment on Ubuntu 24.04; docs/environment-audit.md covers the environment audit.
python3 -m pytest tests/ -q
Provider modules are intentionally small and injectable: each exposes check(api_key, timeout_seconds, timezone_name, http=None, budget=None) so tests run without network access.
Per SECURITY.md: