llm-watcher

01

Reading a row

Every plan gets at least two windows — the rolling five-hour cap and the weekly cap. Each window prints the same three things.

Countdowns show the two largest units with zeros dropped — 2d 13h, 45m, plain 7d for a week untouched. Minutes remaining in a two-day window is not a number anyone acts on, so it is not shown.

02

Pace

Providers report quota in incompatible units, so raw numbers do not compare. Pace normalises them.

pace = fraction of quota consumed ÷ fraction of window elapsed

• 0.7x Headroom remains

  Half the window gone, a third of the quota gone.

• 1.0x Exactly on budget

  Quota lands precisely as the window resets.

• 1.6x Exhausts before reset

  Four fifths spent at the halfway mark.

The notch marks how much of the window has elapsed; the bar is how much quota is gone.

-- means there is no honest signal yet: a window that just reset, or one whose boundaries the provider did not report. A fabricated ratio there reads as an emergency, so none is printed.

03

What it does not do

The absences are the point.

• — No daemon
• — No database
• — No listening port
• — No background process
• — Nothing written into ~/.claude/

The Claude credential store is read, never modified. API keys are referenced by environment variable name and read at runtime — never stored in the config, never accepted as a command-line argument, because argv is visible in ps and lands in shell history.

04

Install

Usage

llm-watcher                            # table
llm-watcher --json                     # machine-readable
llm-watcher --account minimax-max      # one plan (repeatable)
llm-watcher --threshold 1.5            # exit 1 at or past 1.5x
llm-watcher --no-color

Configure

With no config file it falls back to MINIMAX_API_KEY, MINIMAX_MAX_API_KEY and ZHIPU_API_KEY / ZAI_API_KEY, so it works before you write anything. If Claude Code is logged in on this machine, a claude row appears too — no variable needed, because a Claude subscription has no API key to set.

For more than one account per provider — the case this tool exists for — write ~/.config/llm-watcher/config.toml:

[[account]]
name     = "minimax-work"
provider = "minimax"
key_env  = "MINIMAX_API_KEY"

[[account]]
name     = "glm"
provider = "zai"        # aliases: glm, zhipu
key_env  = "ZHIPU_API_KEY"

[[account]]
name     = "claude"
provider = "anthropic"  # aliases: claude, claude-code
                        # no key_env — the token comes
                        # from Claude Code

Exit codes

A single failing account does not abort the run — the error lands on its own row and the other plans still report. --threshold plus --json is enough for a cron job or a waybar module without any of this needing a daemon.

05

Provider status

When a row’s provider has a public status page, llm-watcher fetches it and appends a marker the moment the indicator is anything other than none. A healthy run reads exactly as it did before — the marker is the only difference.

PLAN         5H WINDOW                        WEEKLY
minimax       10% used   0.1x  resets 4h 50m   49% used   0.8x  resets 2d 10h
glm           15% used   0.2x  resets 4h 45m   20% used   0.3x  resets 4d 13h
claude         0% used     --  resets 4h 55m    3% used   0.1x  resets 4d 18h  ⚠ minor — Degraded performance for Claude Opus 5 and Claude Haiku 4.5

The marker carries the Statuspage.io indicator (none · minor · major · critical · maintenance · custom), a colour band by severity, and the first open incident name. none produces no marker, so a row that is healthy prints nothing new — the same shape it had before this feature landed.

Only Anthropic is wired up today (status.claude.com). Adding another provider is one match arm on Provider::status_page_url() plus a fixture in tests/fixtures/. MiniMax and Z.ai return None until their pages are verified.

The status fetch only runs when the quota fetch succeeds, so the hermetic test suite never reaches the network. Failures collapse to an absent field, not an error — the quota row is unaffected.

06

Providers

The asymmetry in that last column is real, not a typo. Getting it backwards produces a 401 that reads exactly like a bad key.

Anthropic’s is the subscription surface, not the pay-as-you-go API — the same data Claude Code’s /usage command shows. No provider documents its response body, so the README records what was captured live, with the real documents kept as fixtures.

Read the full documentation