ai-limits-mqtt/README.md

AI Limits MQTT

Small Go service that publishes Claude Code and Codex CLI status to Home Assistant over MQTT.

What it reports

This publishes the limit/reset style status shown by the interactive CLIs:

• Claude Code: captures /usage in a PTY and parses current-session/current-week percent used and reset text.
• Codex CLI: runs a tiny probe, captures /status in a PTY, and parses Codex's recorded rate_limits object for 5h/week percent used and reset timestamps.

It reports:

• status: ok, limited, auth_required, timeout, or error.
• primary: short window limit, normally 5h/session, with used_percent, window_minutes, resets_at/reset_text where exposed.
• secondary: weekly/all-model limit, with percent and reset data where exposed.
• raw_report: cleaned slash-command output for debugging/comparison with the CLI.
• plan_type: provider plan where exposed.

Token usage is not the main signal. Any local token counters remain as optional attributes only for diagnostics/backward compatibility.

MQTT topics

• ai_limits/availability
• ai_limits/claude/state
• ai_limits/codex/state
• ai_limits/summary/state

Home Assistant discovery is retained under:

• homeassistant/sensor/ai_limits_claude/config
• homeassistant/sensor/ai_limits_codex/config
• homeassistant/sensor/ai_limits_summary/config

Run

docker compose up -d --build

Secrets live in .env and are intentionally gitignored.