tokenmaxxr

Aggregate AI subscription quota usage (Claude, AWS Kiro, ClinePass, Ollama Cloud, OpenCode Go) into one view.

Five providers, one engine, one versioned JSON contract. CLI for bars/dashboards, a DankMaterialShell bar plugin, optional WebUI, optional HTTP API.

Install

# from PyPI (recommended)
uvx tokenmaxxr --json

# from source
git clone https://github.com/Izzur/tokenmaxxr
cd tokenmaxxr
uv pip install -e ".[serve]"  # add [serve] for `tokenmaxxr serve`

Quickstart

tokenmaxxr              # human table
tokenmaxxr --json       # machine-readable schema:1
tokenmaxxr --refresh    # bypass the 300s cache
tokenmaxxr doctor       # diagnose cookie discovery
tokenmaxxr serve        # WebUI + HTTP API

Web UI

tokenmaxxr serve (requires pip install 'tokenmaxxr[serve]') starts a small FastAPI app on 127.0.0.1:8765:

• GET /api/usage — schema:1 document (same as tokenmaxxr --json)
• POST /api/refresh — force a live re-fetch
• GET /api/history?provider=&window= — appended history rows
• GET / — vanilla-JS dashboard (cards + history chart, opt-in 60s auto-refresh)

The dashboard degrades gracefully: with no cookies, every card shows no-auth and a hint.

Output contract

tokenmaxxr --json returns a stable, versioned document:

{
  "schema": 1,
  "fetched_at": "2026-07-22T12:00:00Z",
  "providers": [
    {
      "id": "ollama-cloud",
      "name": "Ollama Cloud",
      "status": "ok",
      "windows": [
        {"label": "5h", "pct_used": 47, "reset_at": "2026-07-22T20:00:00Z"}
      ]
    }
  ]
}

status is one of ok | stale | no-auth | error.

Config

$XDG_CONFIG_HOME/tokenmaxxr/config.toml (default ~/.config/tokenmaxxr/config.toml), optional:

include = ["claude", "kiro"]   # whitelist: only these providers
exclude = ["opencode-go"]      # blacklist: everything except these

include is applied first, then exclude. --provider on the CLI overrides both.

Auth sources

Two kinds of provider:

Token providers never refresh tokens themselves (that could invalidate the CLI's own session). Kiro tokens expire hourly, so an expired one makes tokenmaxxr run kiro-cli whoami, which refreshes in place. An expired Claude token shows as no-auth; run claude once and the next poll succeeds.

Cookie sources

1. --cookie-file SLUG=/path/to/cookies.sqlite or TOKENMAXXR_COOKIE_<DOMAIN> env
2. Firefox-family stores (globbed: ~/.mozilla/firefox/*, ~/.zen/*, Zen/Firefox Flatpak paths, Floorp/LibreWolf/Waterfox)
3. Chromium-family via browser_cookie3 (best-effort, locked keyring → skip)
4. No match → no-auth status + remediation in doctor

Cookies are copied to a temp file before reading (WAL lock-safe). Cache and history live under ~/.local/state/tokenmaxxr/.

DankMaterialShell (Dankbar)

uv tool install tokenmaxxr                       # puts `tokenmaxxr` on ~/.local/bin
git clone https://github.com/Izzur/tokenmaxxr
ln -s "$PWD/tokenmaxxr/dms/TokenMaxxr" ~/.config/DankMaterialShell/plugins/TokenMaxxr

Then DMS Settings → Plugins → enable tokenmaxxr, and add it to a bar section. Pill shows C 3d 4h: for each provider take its longest window (30d, 7d, …), then show the provider whose longest window resets soonest and the countdown to it. Left click opens a popout with every window, progress bar and reset countdown. Right click forces --refresh.

Optional settings in ~/.config/DankMaterialShell/plugin_settings.json:

"tokenMaxxr": { "enabled": true, "command": "tokenmaxxr --json", "interval": 300 }

Waybar

"custom/tokenmaxxr": {
  "exec": "tokenmaxxr --json --provider ollama-cloud",
  "return-type": "json",
  "format": "Ollama 5h: {}%",
  "exec-on-event": true,
  "interval": 600
}

--json is the stable schema:1 contract — jq '.providers[0].windows[0].pct_used' always returns an integer.

fastfetch

"tokenmaxxr": {
  "type": "command",
  "key": "TKN",
  "command": "tokenmaxxr --json | jq -r '.providers[] | select(.status==\"ok\") | \"\\(.id): \\(.windows[0].pct_used)%\"' | paste -sd, -"
}

Headless / --cookie-file

tokenmaxxr --cookie-file ollama-cloud=/srv/cookies/ollama.sqlite --json
# or
TOKENMAXXR_COOKIE_OLLAMA_COM=/srv/cookies/ollama.sqlite tokenmaxxr --json

## Development

```bash
uv sync --extra dev           # set up dev deps (pytest, fastapi, etc.)
uv run python3 -m pytest      # 32 tests, <1s
uv run python3 -m pytest tests/test_providers.py -v   # one file

Provider parser tests live in tests/test_providers.py against HTML/JSON fixtures under tests/fixtures/. To add a fixture, drop a real captured payload into tests/fixtures/<slug>.<ext> and write a test_<slug> that feeds it through RawHtml and asserts on the parsed UsageWindows.

License

MIT