Dashboard Examples¶
Use Lovelace cards with ModelDeck MQTT sensors on a wall tablet or desk display. Ready-to-paste YAML lives in examples/home-assistant/.
Prerequisites¶
- ModelDeck running and MQTT sensors visible under Settings → Devices & services → MQTT
- layout-card (HACS) — required for the full ModelDeck tab (horizontal 4-column layout)
- card-mod (HACS) — optional but recommended for red
auth_errorstyling on status rows
Quick install¶
Compact summary on Overview¶
- Open Overview → pencil (Edit dashboard)
- Add card → Manual
- Paste the contents of
overview-compact.yaml - Drag the card where you want it → Save
Shows dual gauges per provider (primary + weekly/5h where applicable) plus an optional ModelDeck Status row with sensor.modeldeck_*_status for each provider.
Full ModelDeck tab¶
- Edit dashboard → Add view (top tab bar)
- Title:
ModelDeck, icon:mdi:robot-outline - On the new view → Edit → Raw configuration editor
- Paste the contents of
modeldeck-tab.yaml - Save
4-column layout: columns 1–3 are live gauges + entity rows per provider (Codex, Claude, Cursor); column 4 has a 24h mean chart and 7-day history graphs per provider. Requires layout-card (HACS).
Ensure ModelDeck usage entities are not excluded from Recorder so history graphs populate.
Verify entity IDs¶
If a card shows Entity not found:
- Developer tools → States — filter
modeldeck - You should see
sensor.modeldeck_codex_usage_percent,sensor.modeldeck_claude_status, etc. (current since v0.1.5) - If you still see only
sensor.codex_*/sensor.claude_*, upgrade to v0.1.5+ and restart ModelDeck; re-paste YAML from the examples - Confirm IDs match your auth mode — see sensors.md for which entities exist per mode
- An
account_labelin the add-on config changes friendly names only — entity IDs stay the same
Disable the mock provider in production so gauges show real quota data.
Entity reference¶
Canonical IDs — full matrix: sensors.md.
| Card use | Entity (when supported) |
|---|---|
| 5h / primary usage gauge | sensor.modeldeck_{provider}_usage_percent |
| Weekly usage | sensor.modeldeck_{provider}_usage_weekly_percent (Codex subscription, Claude) |
| Cursor Auto pool | sensor.modeldeck_cursor_usage_auto_percent |
| Cursor API pool | sensor.modeldeck_cursor_usage_api_percent |
| Extra usage used/limit | sensor.modeldeck_claude_usage_used, sensor.modeldeck_claude_usage_limit |
| Reset time (5h / billing) | sensor.modeldeck_{provider}_reset_at |
| Weekly reset | sensor.modeldeck_{provider}_reset_weekly_at |
| Plan | sensor.modeldeck_{provider}_plan |
| Health | sensor.modeldeck_{provider}_status (ok = working) |
| Last poll | sensor.modeldeck_{provider}_last_success |
Replace {provider} with codex, claude, or cursor.
Example files¶
| File | Purpose |
|---|---|
overview-compact.yaml |
Overview tab — dual gauges + status (card-mod optional) |
modeldeck-tab.yaml |
Full ModelDeck view — 4-column live + history (layout-card, card-mod optional) |
usage-stack.yaml |
Single-provider stack (Codex example; swap prefix for Claude/Cursor) |
Single usage gauge¶
type: gauge
entity: sensor.modeldeck_codex_usage_percent
name: Codex Usage
min: 0
max: 100
needle: true
severity:
green: 0
yellow: 70
red: 90
Reset timestamp¶
type: entity
entity: sensor.modeldeck_claude_reset_at
name: Claude Reset
Multi-provider grid (minimal)¶
type: grid
columns: 3
cards:
- type: gauge
entity: sensor.modeldeck_codex_usage_percent
- type: gauge
entity: sensor.modeldeck_claude_usage_percent
- type: gauge
entity: sensor.modeldeck_cursor_usage_percent
ESPHome / table displays¶
Any device that subscribes to MQTT can render the same topics. Point an ESPHome text_sensor or sensor at modeldeck/{provider}/usage_percent/state.