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

The CLIs do not expose a stable standalone "remaining quota" API. This service therefore performs a small real CLI probe and classifies the result:

• ok: CLI authenticated and a tiny probe completed.
• limited: output matched rate/usage/quota-limit errors.
• auth_required: login/auth is missing or invalid.
• timeout / error: probe failed for another reason.

It also publishes any usage object returned by the CLI probe:

• Claude: JSON result usage from claude -p ... --output-format json.
• Codex: JSONL usage from codex exec --json turn completion.

It now also reports rolling local token usage for each CLI:

• session_5h.used_tokens and session_5h.percent_used
• week.used_tokens and week.percent_used

The percent fields are computed against env-configured token limits:

• CLAUDE_SESSION_5H_TOKEN_LIMIT
• CLAUDE_WEEK_TOKEN_LIMIT
• CODEX_SESSION_5H_TOKEN_LIMIT
• CODEX_WEEK_TOKEN_LIMIT

Set a limit to 0 to publish raw used tokens without a percentage.

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.