feat: add AI limits MQTT service

README.md

@@ -0,0 +1,52 @@
+# 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
+
+```bash
+docker compose up -d --build
+```
+
+Secrets live in `.env` and are intentionally gitignored.