Skip to content
AutomationNexusPublic

About

Dockerized AI usage and quota bridge for Home Assistant via MQTT.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

196 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ModelDeck

CI Nightly Release Semgrep Docs Security GHCR License: MIT

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).

Current features

  • 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_percent and sensor.modeldeck_cursor_usage_api_percent
  • Claude extra-usage — sensor.modeldeck_claude_usage_used / usage_limit from on-demand budget
  • Dashboard examples — 4-column ModelDeck tab + dual-gauge overview; optional card-mod auth_error styling

See sensors.md for the full sensor matrix.

Breaking change: entity IDs in v0.1.x+

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.

How it works

  1. 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.
  2. ModelDeck polls each enabled provider account on a schedule (default 5 minutes).
  3. 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.

Quick start (Docker)

cp .env.example .env
./ops/bootstrap-config.sh
docker compose -f templates/docker-compose.yml up -d

Edit config/modeldeck.yaml (providers, auth modes) and config/secrets.yaml (tokens and keys). Use bootstrap-config.sh production for real providers. See installation.md.

Home Assistant OS add-on

Install ModelDeck on HAOS directly from this repository — it's also a Home Assistant add-on repository (modeldeck/ = stable channel, modeldeck-nightly/ = nightly channel):

  1. Settings → Add-ons → Add-on store → ⋮ → Repositories → add https://github.com/automationnexus/ModelDeck
  2. Install ModelDeck, open Configuration, fill MQTT + provider sections, Save, Start
  3. Settings → Devices & services → MQTT — confirm ModelDeck devices and sensor.modeldeck_*_status = ok

Full walkthrough: docs/getting-started/haos-addon.md

Getting credentials (all three providers)

HAOS: use the Ingress web UI (recommended)

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.

Docker / CLI: copy tokens manually

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).

OpenAI

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

Claude

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.

Claude OAuth: missing Plan or 5h Reset At?

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

Cursor

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 --full

Merge everything at once:

modeldeck credentials print --all --write-secrets   # writes to config/secrets.yaml

Example secrets.yaml (subscription + cookie + personal)

providers:
  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.


Verify

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.


Documentation

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/

Local development

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev,service]"
.\ops\run-tests.ps1

Branch and release model

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

Non-goals

  • Built-in web dashboard (use Home Assistant Lovelace)
  • Official provider partnerships or guaranteed API stability

License

MIT — see LICENSE.

About

Dockerized AI usage and quota bridge for Home Assistant via MQTT.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages