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

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