Sensors Reference¶
ModelDeck publishes only the sensors your provider and auth mode can populate. Sensors that do not apply to your account are not discovered, so Home Assistant should not show Unknown for missing quota fields.
Full matrix below. For MQTT topic names see mqtt-topics.md.
Quick reference¶
| Entity pattern | Meaning |
|---|---|
sensor.modeldeck_{provider}_usage_percent |
Primary usage % (5h window for Claude; billing cycle for Cursor; subscription % for Codex) |
sensor.modeldeck_{provider}_usage_weekly_percent |
7-day usage % (Claude, Codex subscription) |
sensor.modeldeck_{provider}_reset_at |
Primary window reset time (5h for Claude; billing cycle for Cursor/Codex) |
sensor.modeldeck_{provider}_reset_weekly_at |
Weekly window reset time |
sensor.modeldeck_{provider}_plan |
Plan or subscription tier name |
sensor.modeldeck_cursor_usage_auto_percent |
Cursor Auto + Composer pool % (personal) |
sensor.modeldeck_cursor_usage_api_percent |
Cursor API pool % (personal) |
sensor.modeldeck_{provider}_usage_used |
Absolute spend used (USD) — Claude extra-usage budget or Cursor/Codex API |
sensor.modeldeck_{provider}_usage_limit |
Absolute spend limit (USD) |
sensor.modeldeck_{provider}_credits |
Remaining extra-usage credits (Claude) |
sensor.modeldeck_{provider}_status |
Collector health: ok, auth_error, rate_limited, etc. |
sensor.modeldeck_{provider}_last_success |
Last successful poll timestamp |
Replace {provider} with codex, claude, or cursor.
Provider × auth mode matrix¶
OpenAI Codex¶
| Sensor | subscription |
api |
|---|---|---|
| Usage % | ✓ | — |
| Weekly usage % | ✓ | — |
| Reset at / weekly reset | ✓ | — |
| Credits | ✓* | — |
| Used / Limit | — | Used only |
| Plan | ✓ | ✓ |
| Status / Last success | ✓ | ✓ |
*Credits when the subscription API returns credit data.
Claude¶
| Sensor | cookie |
oauth |
|---|---|---|
| Usage % (5h) | ✓ | ✓ |
| Weekly usage % | ✓ | ✓ |
| Reset at (5h) | ✓ | ✓* |
| Weekly reset at | ✓ | ✓ |
| Used / Limit | ✓** | ✓** |
| Credits | ✓** | ✓** |
| Plan | ✓ | ✓*** |
| Status / Last success | ✓ | ✓ |
Used / Limit / Credits come from Claude extra-usage (on-demand spend budget), not the 5-hour message quota. The 5h quota is sensor.modeldeck_claude_usage_percent.
*OAuth Reset at (5h) appears only when Anthropic returns five_hour.resets_at in the usage API. When the 5h window is idle (0% utilization), the API often omits the timestamp — this is normal.
**Only when extra_usage is present in the API response (monthly_limit > 0 or used_credits > 0 / is_enabled).
***OAuth Plan comes from the usage API when present, from Claude Code subscriptionType in credentials, or from the optional Subscription tier field in the HA add-on Configuration tab.
For full parity with Codex-style sensors (plan + 5h reset more often), use cookie mode on claude.ai Pro/Max.
Cursor¶
| Sensor | personal |
enterprise |
|---|---|---|
| Usage % (total) | ✓ | ✓ |
| Auto + Composer % | ✓ | ✓* |
| API % | ✓ | ✓* |
| Used / Limit | ✓ | ✓ |
| Reset at | ✓ | ✓ |
| Weekly usage | — | — |
| Plan | ✓* | ✓ |
| Status / Last success | ✓ | ✓ |
*Auto/API when the API returns autoPercentUsed / apiPercentUsed. Plan on personal when planName is returned.
Entity ID migration (v0.1.5+)¶
Current (v0.1.5 and later): sensor.modeldeck_{provider}_{metric} — for example sensor.modeldeck_codex_usage_percent, sensor.modeldeck_claude_status.
Historical (v0.1.0–v0.1.4 only): short slugs such as sensor.codex_usage, sensor.codex_collector_status. These were retired in v0.1.5.
If dashboard cards show Entity not found:
- Update ModelDeck to v0.1.5+ and restart the add-on or container.
- In Developer tools → States, search
modeldeck— you should seesensor.modeldeck_*entities. - If you still see only
sensor.codex_*/sensor.claude_*, you are on an old build; upgrade and restart. - Remove stale MQTT entities under Settings → Devices & services → MQTT if duplicates remain.
- Re-paste YAML from overview-compact.yaml and modeldeck-tab.yaml.
| Old short slug (v0.1.0–v0.1.4) | Current (v0.1.5+) |
|---|---|
sensor.codex_usage |
sensor.modeldeck_codex_usage_percent |
sensor.codex_usage_weekly |
sensor.modeldeck_codex_usage_weekly_percent |
sensor.codex_collector_status |
sensor.modeldeck_codex_status |
sensor.claude_usage |
sensor.modeldeck_claude_usage_percent |
sensor.cursor_usage_auto |
sensor.modeldeck_cursor_usage_auto_percent |
Recorder and history graphs¶
Sensors with state_class: measurement (usage %, weekly %, auto/api %) are recorded by Home Assistant Recorder by default.
- Ensure entities are not excluded in Settings → System → Recorder.
- Add the ModelDeck view from modeldeck-tab.yaml (column 4 includes history graphs).
- Default retention applies; adjust in Recorder settings if needed.
Automations¶
Example: notify when any provider hits auth_error:
trigger:
- platform: state
entity_id:
- sensor.modeldeck_codex_status
- sensor.modeldeck_claude_status
- sensor.modeldeck_cursor_status
to: auth_error
action:
- service: notify.persistent_notification
data:
title: ModelDeck auth error
message: "Check credentials for {{ trigger.entity_id }}"
See home-assistant.md for more patterns.