Usage alerts

[MatthiasDurrieu]

I added usage alerts options for the slackbot. I assumed everyone uses our lab plan, which means 9 workspaces so 11.11 $ per person. Based on that, if the usage alert is activated it's gonna DM the user whenever 25% of this has been used on the workspace. Let me know if that sounds useful and if that's a good way to implement it!

Here is in depth automatically generated summary of the changes:

• Adds three new DM commands: alerts on <workspace>, alerts off, alerts status

• A new hourly APScheduler job checks each subscriber's current-month cost against their personal share of the plan budget and DMs them at 25 / 50 / 75 / 100 % — and every 25 % beyond that for over-budget situations

• Subscriptions are persisted in a JSON file (./data/alerts.json by default, configurable via ALERTS_FILE). A ./data:/app/data volume is added to docker-compose.yml so the file survives container restarts

• Two new env vars — MONTHLY_PLAN_LIMIT (default 100) and PLAN_MEMBER_COUNT (default 9) — control the per-user share; no changes needed for the current setup

How it works (design notes)

New module — claude-usage-bot/alerts.py

AlertManager is a thread-safe wrapper around a JSON file. It stores, per Slack user ID: which workspace they watch, whether alerts are enabled, and which percentage thresholds have already triggered a DM this calendar month. Using a month key ("2026-05") means the threshold tracking resets automatically each month without any cron cleanup.

Scheduled job — _check_usage_alerts()

Runs every hour via APScheduler. For each active subscriber it calls query_cost_current_month() + filter_data_for_workspace() (both already existed), sums the cost in cents, converts to USD, and walks 25 % increments up to the current spend percentage. Any threshold not yet recorded gets a DM and is then written to the JSON file so it isn't sent again.

Workspace validation on subscribe

alerts on <workspace> calls workspace_name_to_id() immediately, so the user gets a clear error message if they mistype a workspace name rather than silently never receiving alerts.

Test plan

• DM the bot alerts on <your-workspace> — should reply with confirmation and your monthly share amount

• DM alerts status — should show workspace name and "none yet this month"

• DM alerts off — should confirm; alerts status should then show no subscription

• DM alerts on <invalid-workspace> — should reply with a workspace-not-found error

• Verify ./data/alerts.json is created and updated on subscribe/unsubscribe

• Add MONTHLY_PLAN_LIMIT and PLAN_MEMBER_COUNT to your .env (or leave them out to use the defaults) and restart the bot

• Confirm docker-compose up creates the ./data mount and the file persists across docker-compose restart