Env-driven Config fails fast on missing required values; LOCAL_MODE relaxes
the K8s-specific knobs so the bot can run from a plain docker container
against a bind-mounted oauth-tokens dir. Entrypoint wires together token
refresh, usage poll, alert computation, optional armed cold-start message,
E2EE Matrix send, and atomic state persistence. Adds a pytest -m live
smoke test that hits the real /api/oauth/usage endpoint, skipped by
default so CI stays offline.
Targets the undocumented /api/oauth/usage endpoint that Claude Code uses
internally for /status. Token refresh uses /v1/oauth/token with the public
Claude Code client_id. On refresh, new tokens are persisted back via either
in-cluster K8s Secret PATCH (production) or atomic per-file write to the
mounted dir (local mode). utilization is converted from API's 0-100 percent
to internal 0.0-1.0 fractional at the boundary.
Pure functions for the watcher's core: compute_alerts decides what to emit
given prior state vs. fresh usage, with configurable threshold list and a
reset-shift tolerance to filter minute-boundary jitter. State is atomically
persisted as JSON. Alerts render to (plain, html) tuples for Matrix, with
severity-colored percentages, blockquote framing, and a Unicode progress
bar for the cold-start armed message.
Python 3.14 package layout for claude-matrix-bot, with reset_watcher as its
first feature. requirements pin matrix-nio[e2e] for E2EE and requests for
sync HTTP.
vikingowl