ModelDeck is a Dockerized AI usage and quota bridge for Home Assistant. It collects account-level usage, limits, reset times, credits, and plan data from OpenAI, Claude, and Cursor, then publishes MQTT Discovery sensors for dashboards and automations.
Status: v0.0.1 on main (:latest); integration builds on dev (:nightly).
- Metric-aware MQTT — only discovers sensors your auth mode can populate (no Unknown quota fields)
- Stable entity IDs —
sensor.modeldeck_{provider}_{metric}(see sensors.md) - Cursor dual pools —
sensor.modeldeck_cursor_usage_auto_percentandsensor.modeldeck_cursor_usage_api_percent - Claude extra-usage —
sensor.modeldeck_claude_usage_used/usage_limitfrom on-demand budget - Dashboard examples — 4-column ModelDeck tab + dual-gauge overview; optional card-mod
auth_errorstyling
See sensors.md for the full sensor matrix.
Entity IDs now include an account slug:
sensor.modeldeck_{provider}_{account}_{metric}
Example: sensor.modeldeck_claude_default_usage_percent. The default account is used when
configuring through the add-on static options or a single secrets block. Existing dashboards
referencing sensor.modeldeck_{provider}_{metric} must be updated. Old MQTT topics are
retired automatically on first startup.
- Add provider accounts via the HAOS Ingress web UI or CLI login wizard (Claude/Codex), or
paste tokens/cookies directly into the add-on Configuration tab or
secrets.yaml. - ModelDeck polls each enabled provider account on a schedule (default 5 minutes).
- Sensors appear in Home Assistant via MQTT Discovery — for example
sensor.modeldeck_codex_default_usage_percent,sensor.modeldeck_claude_default_status.
Each account gets its own HA device: OpenAI (default), Claude (default), etc.
ModelDeck does not log you in. Copy credentials once; the service reuses them on each poll. OAuth-based modes can auto-refresh tokens when configured.
cp .env.example .env
./ops/bootstrap-config.sh
docker compose -f templates/docker-compose.yml up -dEdit config/modeldeck.yaml (providers, auth modes) and config/secrets.yaml (tokens and keys). Use bootstrap-config.sh production for real providers. See installation.md.
Install ModelDeck on HAOS directly from this repository — it's also a Home Assistant add-on repository (modeldeck/ = stable channel, modeldeck-nightly/ = nightly channel):
- Settings → Add-ons → Add-on store → ⋮ → Repositories → add
https://github.com/automationnexus/ModelDeck - Install ModelDeck, open Configuration, fill MQTT + provider sections, Save, Start
- Settings → Devices & services → MQTT — confirm ModelDeck devices and
sensor.modeldeck_*_status=ok
Full walkthrough: docs/getting-started/haos-addon.md
Open Settings → Add-ons → ModelDeck → Open Web UI and follow the login wizard. No manual token copying needed for Claude or Codex. Cursor still requires a token paste.
For isolated, logout-proof credentials: the wizard creates its own OAuth session per account. Logging out of Claude CLI or Codex CLI on your PC will not affect HAOS accounts that were authenticated through the web UI.
Pick the auth mode that matches how you pay, then copy the listed values into
config/secrets.yaml (Docker) or the add-on Configuration tab (HAOS).
| Auth mode | Account type | What to copy | Where to get it |
|---|---|---|---|
subscription |
ChatGPT Plus/Pro / Codex plan | access_token, refresh_token, account_id |
Codex CLI → ~/.codex/auth.json after login |
api |
OpenAI Platform org billing | api_key (sk-admin-…) |
Organization Admin Keys |
CLI helper (on a PC with auth files):
modeldeck credentials print --provider codex --full| Auth mode | Account type | What to copy | Where to get it |
|---|---|---|---|
cookie |
claude.ai Pro/Max | session_token (sessionKey), org_id (lastActiveOrg) |
Browser DevTools → Cookies → https://claude.ai while signed in |
oauth |
Claude Code | access_token, refresh_token; optional subscription_tier (HA add-on) |
~/.claude/.credentials.json → claudeAiOauth after Claude Code login |
For cookie mode HTTP 403, copy all four claude.ai cookies (sessionKey, lastActiveOrg, cf_clearance, anthropic-device-id). In Docker, cf_clearance is IP-bound, so run ModelDeck on the same host as the browser if 403 persists. OAuth mode is for Claude Code, not claude.ai Pro/Max.
ModelDeck only discovers a sensor when the provider returns data for that field. OAuth mode often shows Usage % and Weekly usage but not every field Codex publishes — this is usually not a bug.
| Sensor | Entity | OAuth behavior |
|---|---|---|
| Usage % (5h) | sensor.modeldeck_claude_usage_percent |
Usually present |
| Weekly usage % | sensor.modeldeck_claude_usage_weekly_percent |
Usually present |
| Weekly reset | sensor.modeldeck_claude_reset_weekly_at |
Usually present |
| Reset At (5h) | sensor.modeldeck_claude_reset_at |
Often missing when Anthropic returns five_hour.resets_at: null (common at 0% 5h utilization) |
| Plan | sensor.modeldeck_claude_plan |
From API/credentials when available; set Subscription tier in the HA add-on (e.g. Pro, Max) or use cookie mode |
For full parity with Codex-style sensors (Plan + 5h reset more reliably), use cookie mode on claude.ai Pro/Max. Details: sensors.md.
modeldeck credentials print --provider claude --full| Auth mode | Account type | What to copy | Where to get it |
|---|---|---|---|
personal |
Pro/Ultra individual | session_token or access_token |
Cookie: DevTools → WorkosCursorSessionToken at cursor.com/dashboard/usage. JWT: cursorAuth/accessToken in Cursor state.vscdb |
enterprise |
Team / Enterprise | admin_api_key |
cursor.com/dashboard → Settings → Advanced → Admin API Keys |
modeldeck credentials print --provider cursor --fullMerge everything at once:
modeldeck credentials print --all --write-secrets # writes to config/secrets.yamlproviders:
codex:
access_token: "eyJ..."
refresh_token: "rt_..."
account_id: "user-..."
claude:
session_token: "sk-ant-sid01-..."
org_id: "org_..."
cursor:
session_token: "..."Match auth_mode in modeldeck.yaml (or the add-on UI) to each block. Details: credentials.md.
| Check | Expected |
|---|---|
sensor.modeldeck_codex_status |
ok |
sensor.modeldeck_claude_status |
ok (if enabled) |
sensor.modeldeck_cursor_status |
ok (if enabled) |
sensor.modeldeck_codex_usage_percent |
% used (subscription) or spend (api) |
| Poll interval | Updates within configured interval (default 5 min) |
If status is auth_error, re-copy credentials and confirm auth mode matches your account type.
| Need | Document |
|---|---|
| Install (Docker) | docs/getting-started/installation.md |
| Install (HAOS add-on) | docs/getting-started/haos-addon.md |
| Provider credentials | docs/guides/credentials.md |
| Configure providers | docs/admin/configuration.md |
| MQTT topics | docs/guides/mqtt-topics.md |
| Sensors (per auth mode) | docs/guides/sensors.md |
| Dashboard examples | docs/guides/dashboard.md |
| Home Assistant | docs/guides/home-assistant.md |
| Full docs site | https://automationnexus.github.io/ModelDeck/ |
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev,service]"
.\ops\run-tests.ps1| Branch | Purpose |
|---|---|
dev |
Day-to-day integration; PRs from feature branches; :nightly image on merge |
main |
Stable line; PR from dev only; semver tag + :latest on merge |
- Built-in web dashboard (use Home Assistant Lovelace)
- Official provider partnerships or guaranteed API stability
MIT — see LICENSE.