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