MQTT Topics¶
Prefix defaults to modeldeck. Discovery uses homeassistant.
ModelDeck discovers only supported metrics for your provider auth mode. See sensors.md for the full matrix.
Bridge¶
| Topic | Payload |
|---|---|
modeldeck/bridge/status |
online / offline |
Per provider¶
| Metric | MQTT state topic | Home Assistant entity (example: codex) |
|---|---|---|
| Usage % | modeldeck/{provider}/usage_percent/state |
sensor.modeldeck_{provider}_usage_percent |
| Used | modeldeck/{provider}/usage_used/state |
sensor.modeldeck_{provider}_usage_used |
| Limit | modeldeck/{provider}/usage_limit/state |
sensor.modeldeck_{provider}_usage_limit |
| Reset at | modeldeck/{provider}/reset_at/state |
sensor.modeldeck_{provider}_reset_at |
| Weekly usage % | modeldeck/{provider}/usage_weekly_percent/state |
sensor.modeldeck_{provider}_usage_weekly_percent |
| Weekly reset at | modeldeck/{provider}/reset_weekly_at/state |
sensor.modeldeck_{provider}_reset_weekly_at |
| Auto + Composer % | modeldeck/{provider}/usage_auto_percent/state |
sensor.modeldeck_{provider}_usage_auto_percent |
| API % | modeldeck/{provider}/usage_api_percent/state |
sensor.modeldeck_{provider}_usage_api_percent |
| Credits | modeldeck/{provider}/credits/state |
sensor.modeldeck_{provider}_credits |
| Plan | modeldeck/{provider}/plan/state |
sensor.modeldeck_{provider}_plan |
| Collector status | modeldeck/{provider}/status/state |
sensor.modeldeck_{provider}_status |
| Last success | modeldeck/{provider}/last_success/state |
sensor.modeldeck_{provider}_last_success |
Example payloads: 42.5, 850, 2000, ISO 8601 timestamps, Pro, ok / auth_error, etc. Percent values are rounded to one decimal.
Discovery¶
homeassistant/sensor/modeldeck_{provider}_{metric}/config — retained JSON discovery payload.
Examples: homeassistant/sensor/modeldeck_codex_usage_percent/config, homeassistant/sensor/modeldeck_cursor_usage_auto_percent/config, homeassistant/sensor/modeldeck_claude_status/config.
The JSON unique_id field is modeldeck_{provider}_{metric} and matches the entity_id suffix.
Subset discovery and retirement¶
On each discovery refresh, ModelDeck publishes configs only for metrics supported by the current snapshot. Previously published sensors that are no longer supported receive an empty retained payload on their discovery topic so Home Assistant can remove them. After upgrading from 0.0.x, delete any remaining Unknown entities manually if needed.