tokenmaxxr 1.0.0__tar.gz

tokenmaxxr-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install package
+        run: uv sync --all-extras --dev
+      - name: Run tests
+        run: uv run pytest -v

tokenmaxxr-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    if: github.event_name == 'release'
+    permissions:
+      id-token: write  # for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tokenmaxxr-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+/dist/
+.eggs/
+*.egg
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Editor
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# State
+.cookies/
+local_state/
+
+# Test artifacts
+*.db
+*.sqlite

tokenmaxxr-1.0.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here.
+This project follows [Keep a Changelog](https://keepachangelog.com/) and
+[Semantic Versioning](https://semver.org/).
+
+## 1.0.0 — 2026-07-23
+
+First stable release. Aggregates AI subscription quota usage from three
+providers into one versioned JSON document.
+
+### Added
+- Three providers: OpenCode Go, ClinePass, Ollama Cloud.
+- `tokenmaxxr` CLI — human table (default), `--json` schema:1 document,
+  `--refresh` (bypass 300s cache), `--provider` filter (repeatable).
+- `tokenmaxxr --version` and `tokenmaxxr.__version__`.
+- `tokenmaxxr doctor` — diagnose cookie discovery per provider.
+- `tokenmaxxr serve` — FastAPI WebUI + HTTP API on `127.0.0.1:8765`
+  (`/api/usage`, `/api/refresh`, `/api/history`, vanilla-JS dashboard).
+- Cookie discovery chain: `--cookie-file`/`TOKENMAXXR_COOKIE_*` env →
+  Firefox-family stores (Mozilla, Zen, Flatpak Zen, Floorp, LibreWolf,
+  Waterfox) → Chromium-family via `browser-cookie3` → `no-auth`.
+- WAL-safe cookie reads (temp-file copy), 300s cache, and history
+  append under `~/.local/state/tokenmaxxr/`.
+- Versioned `schema:1` JSON contract with `ok|stale|no-auth|error` status.
+- CI matrix (Python 3.10–3.13), OIDC trusted publishing workflow.
+
+### Fixed
+- WebUI dashboard now ships in the wheel (`.gitignore` `dist/` rule was
+  excluding `tokenmaxxr/_webui/dist/`; scoped to `/dist/`).

tokenmaxxr-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izzur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenmaxxr-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: tokenmaxxr
+Version: 1.0.0
+Summary: Aggregate AI subscription quota usage (OpenCode Go, ClinePass, Ollama Cloud) into one view.
+Project-URL: Homepage, https://github.com/Izzur/tokenmaxxr
+Project-URL: Bug Tracker, https://github.com/Izzur/tokenmaxxr/issues
+Author-email: Izzur <13365626+Izzur@users.noreply.github.com>
+Maintainer-email: Izzur <13365626+Izzur@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,cline,fastfetch,ollama,opencode,quota,usage,waybar
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: browser-cookie3>=0.20
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.110; extra == 'serve'
+Requires-Dist: uvicorn>=0.27; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# tokenmaxxr
+
+Aggregate AI subscription quota usage (OpenCode Go, ClinePass, Ollama Cloud) into one view.
+
+Three providers, one engine, one versioned JSON contract. CLI for bars/dashboards, optional WebUI, optional HTTP API.
+
+## Install
+
+```bash
+# 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
+
+```bash
+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:
+
+```json
+{
+  "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`.
+
+## 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/`.
+
+## Waybar
+
+```json
+"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
+
+```text
+"tokenmaxxr": {
+  "type": "command",
+  "key": "TKN",
+  "command": "tokenmaxxr --json | jq -r '.providers[] | select(.status==\"ok\") | \"\\(.id): \\(.windows[0].pct_used)%\"' | paste -sd, -"
+}
+```
+
+## Headless / `--cookie-file`
+
+```bash
+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 `UsageWindow`s.
+
+## License
+
+MIT

tokenmaxxr-1.0.0/README.md

@@ -0,0 +1,118 @@
+# tokenmaxxr
+
+Aggregate AI subscription quota usage (OpenCode Go, ClinePass, Ollama Cloud) into one view.
+
+Three providers, one engine, one versioned JSON contract. CLI for bars/dashboards, optional WebUI, optional HTTP API.
+
+## Install
+
+```bash
+# 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
+
+```bash
+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:
+
+```json
+{
+  "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`.
+
+## 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/`.
+
+## Waybar
+
+```json
+"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
+
+```text
+"tokenmaxxr": {
+  "type": "command",
+  "key": "TKN",
+  "command": "tokenmaxxr --json | jq -r '.providers[] | select(.status==\"ok\") | \"\\(.id): \\(.windows[0].pct_used)%\"' | paste -sd, -"
+}
+```
+
+## Headless / `--cookie-file`
+
+```bash
+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 `UsageWindow`s.
+
+## License
+
+MIT

tokenmaxxr-1.0.0/openspec/changes/archive/2026-07-22-add-quota-aggregator/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-22

tokenmaxxr-1.0.0/openspec/changes/archive/2026-07-22-add-quota-aggregator/design.md

@@ -0,0 +1,107 @@
+## Context
+
+Greenfield repo (`~/z/tokenmaxxr`, currently only `openspec/`). The user subscribes to three AI coding services — OpenCode Go ($10/mo), ClinePass ($9.99/mo), Ollama Cloud — and wants one place to see quota usage. Investigation on 2026-07-22 established:
+
+- **No official usage APIs exist.** OpenCode (anomalyco/opencode#18648) and Ollama (ollama/ollama#15663) both closed feature requests without shipping an endpoint; ClinePass documents dashboard-only usage. Web-scraping with a session cookie is the only path.
+- **Inference credentials don't work for usage.** The API keys/OAuth tokens in `~/.local/share/opencode/auth.json` and `~/.config/pi/agent/auth.json` authenticate chat-completions calls only. Usage data lives behind the web dashboard session cookie.
+- **Prior art exists for 2 of 3 providers.** `dzackgarza/usage-limits` (Python) has working OpenCode Go and Ollama Cloud scrapers; `~hrbrmstr/ollama-usage` (Go) has another Ollama one. ClinePass has no published scraper, but its selectors were verified from a real dashboard dump.
+- **The user's browser is Zen (Firefox fork) via Flatpak.** Verified live cookies for all three target domains in `~/.var/app/app.zen_browser.zen/.zen/skn3ylbm.Default (release)/cookies.sqlite` (plaintext SQLite — no keychain dance).
+
+Downstream consumers already queued: Waybar (exec + JSON), fastfetch custom module (exec one-liner), and "other people's Java/Python/Go/TS projects" — which all collapse into one requirement: a stable, versioned JSON contract plus exec/HTTP access.
+
+## Goals / Non-Goals
+
+**Goals:**
+- One Python engine that scrapes all three dashboards and normalizes to a versioned JSON schema (`schema: 1`).
+- Browser-agnostic cookie resolution: works on Zen/Firefox/Chromium/Flatpak variants without per-browser code forks; headless override via `--cookie-file`/env.
+- Cache-by-default (TTL 300s) with explicit `--refresh`; stale-fallback when a fetch fails; failure-tolerant per provider (one provider's breakage never blocks the others).
+- Append-only `history.jsonl` so the WebUI can graph trends without a database.
+- CLI with human table + `--json`; `doctor` command for auth diagnostics.
+- Optional `tokenmaxxr serve` (FastAPI) + vanilla-JS WebUI (single `index.html` + `styles.css` + `app.js` served from `tokenmaxxr/_webui/dist/`, no build step) with opt-in auto-refresh and canvas2D history graphs. See `specs/web-dashboard/spec.md` for the rejection note on the Vite + React + shadcn/ui + TanStack Query + Recharts stack.
+- Ship as a PyPI package runnable via `uvx tokenmaxxr`.
+
+**Non-Goals:**
+- Per-language SDKs (Java/Go/TS). The JSON contract + CLI exec + HTTP API covers them.
+- A Go static CLI binary (deferred until a real consumer needs it).
+- Historical backfill, a real database, pruning/compaction of `history.jsonl` (revisit when it's actually big).
+- Auto-refresh as default behavior in the WebUI (opt-in only).
+- Notifications/alerting (ntfy, email) — usage-limits does this; we don't, yet.
+- Multi-account per provider (one cookie set per domain).
+
+## Decisions
+
+### D1: One Python engine + JSON contract, not N SDKs
+
+The "reusable for other people" requirement is satisfied by a **stable versioned output schema** consumed via `--json` (exec) or HTTP — not by writing the scraper in four languages. Scraper markup churns; one codebase to fix beats four.
+
+- Alternatives considered: 4 SDKs (rejected — 4× maintenance on the fragile part); Go CLI reimplementation now (rejected — parallel experiment on an unstabilized schema; revisit post-1.0 if static-binary demand appears).
+
+### D2: CLI is Python, not Go/Rust
+
+`tokenmaxxr` is a console-script entry point of the core package. The CLI is a thin formatter over `fetch()` output; putting it in the same language as the engine removes an entire sync surface. Static-binary distribution is a "later" port of a stabilized schema.
+
+### D3: Cookie resolution chain (custom thin resolver over browser_cookie3)
+
+Per provider domain, resolve cookies in order:
+1. `--cookie-file <path>` / `TOKENMAXXR_COOKIE_<PROVIDER>` env (headless/servers).
+2. Firefox-family stores, globbed: `~/.mozilla/firefox/*`, `~/.zen/*`, `~/.var/app/app.zen_browser.zen/.zen/*`, `~/.var/app/org.mozilla.firefox/...`, floorp/librewolf/waterfox equivalents → `cookies.sqlite` (plaintext).
+3. Chromium-family via `browser_cookie3` (needs unlocked libsecret keyring — best-effort).
+4. No match → provider status `no-auth`; `doctor` prints remediation.
+
+Always **copy `cookies.sqlite` to a temp file before reading** (WAL lock conflicts with a running browser). browser_cookie3 doesn't know Zen's Flatpak path, so we glob ourselves and hand it paths.
+
+- Alternatives considered: pure browser_cookie3 (rejected — misses Zen Flatpak, the user's actual setup); Playwright/selenium automation (rejected — heavyweight, brittle, and unnecessary when the cookie store is readable).
+
+### D4: Per-provider scrapers behind a common interface
+
+```python
+class Provider(Protocol):
+    slug: str
+    def fetch_raw(self, cookies: CookieJar) -> RawHtml: ...
+    def to_rows(self, raw: RawHtml) -> list[UsageWindow]: ...
+```
+
+Anchor on **semantic HTML** (ARIA roles/labels, `data-slot`, `data-time`) rather than utility classes:
+
+| Provider | URL | Anchor | pct | reset |
+|---|---|---|---|---|
+| opencode-go | `opencode.ai/workspace/{id}/go` (id via `/auth` redirect) | `[data-slot=usage-item]` | `[data-slot=usage-value]` | `[data-slot=reset-time]` rel. text |
+| clinepass | `app.cline.bot/dashboard/subscription?personal=true` | `[role=progressbar][aria-label$=" usage"]` | `@aria-valuenow` | sibling "Resets in…" rel. text |
+| ollama-cloud | `ollama.com/settings` | `[aria-label^="Session usage "]/["Weekly usage "]` | aria-label text | sibling `[data-time]` ISO |
+
+Relative reset strings parse to absolute UTC (`now + delta`) at fetch time.
+
+### D5: Cache = latest-value JSON; history = separate JSONL
+
+```
+~/.local/state/tokenmaxxr/
+├── cache/<provider>.json     # {fetched_at, payload}; TTL 300s; --refresh deletes first
+└── history.jsonl             # {"ts","provider","window","pct_used"} per window per fetch
+```
+
+Cache answers "what's the number now" fast; history answers "how did it trend". On fetch failure within TTL: serve stale cache and mark provider `stale`. On failure with no cache: status `error` (or `no-auth` for cookie problems). Never let one provider's failure poison the others' output.
+
+### D6: WebUI = `tokenmaxxr serve` hosting a vanilla-JS single page
+
+FastAPI serves `GET /api/usage` (schema:1 JSON), `GET /api/history?provider=&window=`, `POST /api/refresh`, and statics from `tokenmaxxr/_webui/dist/`. The frontend is a single `index.html` + `styles.css` + `app.js` — no build step, no `node_modules`. The history chart is a hand-rolled canvas2D line plot. This keeps one process owning cache+history — no dual-write consistency problem. Opt-in 60s auto-refresh via a manual toggle button.
+
+- Alternatives considered: Vite + React + shadcn/ui + TanStack Query + Recharts (rejected 2026-07-22 — dashboard is one route with three data sources, the JSON contract is the only real API surface, and pulling in a build pipeline + node_modules would add a JS toolchain the project otherwise does not need). See `openspec/changes/add-quota-aggregator/specs/web-dashboard/spec.md` for the spec-side rejection note and the threshold for revisiting.
+
+- Revisit if any of: a second route appears, the chart requirements exceed what canvas2D can draw, or vanilla-JS component complexity crosses ~500 lines. At that point Recharts + TanStack Query is the preferred upgrade path.
+
+## Risks / Trade-offs
+
+- Vendor redesigns dashboard markup → scraper breaks. → Semantic anchors (D4) reduce frequency; per-provider isolation means one breakage ≠ total outage; `error` status is explicit in output; prior-art repos act as an early-warning canary.
+- Session cookie expires/revoked → provider can't fetch. → Status becomes `no-auth`; `doctor` names the exact missing domain; re-login in the browser fixes it with zero config changes.
+- Cookie extraction touches sensitive data → misuse risk. → Read-only, copy-before-read, cookies only ever sent to their own domain over HTTPS; cache/history contain only percentages/timestamps, never credentials.
+- Chromium keyring locked → Chromium path fails silently. → Expected; chain order prefers Firefox-family (plaintext), and `doctor` reports which stores were readable.
+- Scraping may violate ToS. → Accepted: read-only, low-frequency (TTL-gated), same data the user sees in their own dashboard; both prior-art projects operate the same way.
+- Relative reset-time parsing is locale/fragile → wrong reset_at. → Ollama gives ISO via `data-time` (parse that preferentially); others get a regex over "Resets in Nd Nh Nm" with unit tests against the captured dump.
+
+## Migration Plan
+
+Greenfield — no migration. Rollout: implement core → CLI → serve/WebUI in the order given in `tasks.md`. Rollback is `pip uninstall`; all state lives under `~/.local/state/tokenmaxxr/` and is safe to delete.
+
+## Open Questions
+
+- Exact Zen non-Flatpak Linux path (`~/.zen` vs XDG data dir) — glob both; only Flatpak verified so far.

tokenmaxxr-1.0.0/openspec/changes/archive/2026-07-22-add-quota-aggregator/proposal.md

@@ -0,0 +1,35 @@
+## Why
+
+Checking quota usage for three AI subscriptions (OpenCode Go, ClinePass, Ollama Cloud) means opening three different web dashboards by hand. None of the providers exposes an official usage/quota API (confirmed: anomalyco/opencode#18648 closed without an endpoint, ollama/ollama#15663 closed without an endpoint, ClinePass documents dashboard-only usage), so the data has to be scraped from the dashboards with a browser session cookie. tokenmaxxr centralizes that scrape behind one engine, one versioned JSON contract, and a CLI/WebUI on top.
+
+## What Changes
+
+- New Python core package (`core/tokenmaxxr/`): provider plugins that fetch and parse usage HTML, normalize results into a versioned JSON schema (`schema: 1`), and persist results.
+- Three providers: `opencode-go`, `clinepass`, `ollama-cloud` (ClinePass selectors verified against a real dashboard dump; the other two crib from published prior art).
+- Browser-agnostic cookie resolution chain: explicit `--cookie-file`/env override → glob of Firefox-family stores (incl. Zen Flatpak paths) → Chromium-family best-effort → `no-auth` status with doctor hint. Cookies are copied to a temp file before reading (WAL lock on running browsers).
+- Per-provider TTL cache (default 300s) as JSON files under `~/.local/state/tokenmaxxr/cache/`; `--refresh` bypasses the cache. Failures fall back to stale cache when available.
+- Append-only history log `~/.local/state/tokenmaxxr/history.jsonl` written on every successful fetch (drives WebUI graphs).
+- `tokenmaxxr` CLI: human table output (default) and `--json` (the stable contract for Waybar/fastfetch/any consumer), plus `tokenmaxxr doctor` (profile + per-domain cookie presence report).
+- Optional `tokenmaxxr serve`: FastAPI server exposing the JSON contract + history, serving the WebUI build.
+- Vanilla-JS WebUI (`tokenmaxxr/_webui/dist/`): single `index.html` + `styles.css` + `app.js` (no build step, no `node_modules`); opt-in auto-refresh via a manual toggle, history graphs hand-rolled on canvas2D. See `specs/web-dashboard/spec.md` for the rejection note on Vite + React + shadcn/ui + TanStack Query + Recharts and the threshold for revisiting that stack.
+- Distribution via PyPI/`uvx tokenmaxxr`. No per-language SDKs — other languages consume the JSON contract or exec the CLI.
+
+## Capabilities
+
+### New Capabilities
+- `usage-collection`: Provider plugins that authenticate via resolved browser cookies, fetch usage dashboards, parse them into normalized usage windows (label, pct_used, reset_at), and surface per-provider status (`ok`/`stale`/`error`/`no-auth`).
+- `usage-caching`: TTL cache of the latest fetch per provider, force-refresh bypass, stale-fallback on fetch failure, and append-only history logging of successful fetches.
+- `cli-output`: The `tokenmaxxr` command — table and `--json` output of the versioned schema, `--refresh`, per-provider selection, and the `doctor` diagnostics command.
+- `web-dashboard`: Optional `tokenmaxxr serve` HTTP API (current usage + history) and the vanilla-JS WebUI with opt-in auto-refresh and canvas2D history graphs.
+
+### Modified Capabilities
+<!-- None — greenfield repo, no existing specs. -->
+
+## Impact
+
+- **Code**: greenfield repo; adds `core/`, `cli` entry point, `web/`, `openspec/` artifacts.
+- **Dependencies (core)**: `requests`, `beautifulsoup4`, `browser_cookie3`, `fastapi`+`uvicorn` (serve only). Web: zero — single static page served from `tokenmaxxr/_webui/dist/`, no build toolchain.
+- **Data**: writes only under `~/.local/state/tokenmaxxr/` (cache + history). Reads browser cookie stores (copy-before-read, never mutates).
+- **Security**: reads sensitive session cookies locally; never transmits them anywhere except the owning provider's domain over HTTPS. `history.jsonl` and cache contain only percentages/timestamps — no credentials.
+- **Consumers**: Waybar (exec + JSON), fastfetch custom module (exec one-liner), any language via `--json` or the HTTP API.
+- **Fragility (accepted)**: scrapers depend on vendor dashboard markup; a redesign degrades one provider to `error` status without affecting others.

tokenmaxxr-1.0.0/openspec/changes/archive/2026-07-22-add-quota-aggregator/specs/cli-output/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Versioned JSON output contract
+
+The CLI SHALL support `--json` producing a stable, versioned JSON document. The document MUST include a top-level `schema` field (integer, currently `1`), `fetched_at` (UTC ISO 8601), and a `providers` array. Each provider entry MUST include `id`, `name`, `status` (`ok`, `stale`, `error`, or `no-auth`), and a `windows` array of `{label, pct_used, reset_at}` objects. The schema version MUST NOT change without a corresponding spec change.
+
+#### Scenario: Machine consumers get stable shape
+- **WHEN** any consumer runs `tokenmaxxr --json`
+- **THEN** the output parses against the schema:1 contract regardless of which providers succeeded or failed
+
+#### Scenario: Waybar-style consumption
+- **WHEN** a consumer extracts `providers[i].windows[0].pct_used` from `--json` output
+- **THEN** the value is an integer percentage suitable for direct display
+
+### Requirement: Human table output
+
+By default (no `--json`), the CLI SHALL print a human-readable table listing each provider, its windows, percentage used, and reset time. Providers with non-`ok` status MUST be visibly marked.
+
+#### Scenario: Default invocation prints table
+- **WHEN** the user runs `tokenmaxxr` with no flags
+- **THEN** a table of all providers' windows is printed, with stale/error/no-auth providers marked
+
+### Requirement: Refresh and provider selection flags
+
+The CLI SHALL support `--refresh` (bypass cache) and a provider-selection option (e.g. `--provider opencode-go`, repeatable) restricting collection to the named providers.
+
+#### Scenario: Single provider query
+- **WHEN** the user runs `tokenmaxxr --provider ollama-cloud`
+- **THEN** only the ollama-cloud provider is collected and rendered
+
+### Requirement: Doctor diagnostics
+
+The CLI SHALL provide `tokenmaxxr doctor`, which MUST report, for each provider: which cookie stores were discovered, whether cookies for the provider's domain were found, and the remediation step when missing. Doctor MUST NOT print cookie values.
+
+#### Scenario: Missing cookie remediation
+- **WHEN** no cookie exists for a provider's domain
+- **THEN** doctor names the missing domain and instructs the user to log in via their browser (or use `--cookie-file`)
+
+#### Scenario: Cookie values never shown
+- **WHEN** doctor finds valid cookies for all providers
+- **THEN** it reports presence only, never cookie contents
+
+### Requirement: Distribution as installable package
+
+The core engine and CLI SHALL be distributed as a single Python package installable from PyPI and runnable via `uvx tokenmaxxr`.
+
+#### Scenario: Run without install
+- **WHEN** a user runs `uvx tokenmaxxr --json`
+- **THEN** the command works without a prior explicit install step

tokenmaxxr-1.0.0/openspec/changes/archive/2026-07-22-add-quota-aggregator/specs/usage-caching/spec.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Per-provider TTL cache
+
+The system SHALL cache the latest successful fetch per provider as a JSON file under `~/.local/state/tokenmaxxr/cache/<provider>.json`, recording the fetch timestamp and the normalized payload. The default TTL MUST be 300 seconds. When a cached entry is younger than the TTL, the system MUST return the cached payload without contacting the provider.
+
+#### Scenario: Cache hit within TTL
+- **WHEN** a fetch is requested and a cache entry younger than the TTL exists
+- **THEN** the cached payload is returned and no network request is made
+
+#### Scenario: Cache miss after TTL
+- **WHEN** a fetch is requested and the cache entry is older than the TTL (or absent)
+- **THEN** the provider is fetched live and the cache file is overwritten on success
+
+### Requirement: Force refresh
+
+The system SHALL support a `--refresh` flag (and equivalent API trigger) that bypasses the cache and fetches all selected providers live.
+
+#### Scenario: Refresh bypasses fresh cache
+- **WHEN** the user runs with `--refresh` and a fresh cache entry exists
+- **THEN** the system fetches live anyway and overwrites the cache on success
+
+### Requirement: Stale fallback on failure
+
+When a live fetch fails and a cache entry exists (of any age), the system SHALL serve the stale cached payload and mark that provider's status as `stale`. When a live fetch fails and no cache exists, the provider's status MUST be `error`.
+
+#### Scenario: Stale data beats no data
+- **WHEN** a live fetch raises and a cache entry exists
+- **THEN** output shows the cached values with status `stale`
+
+#### Scenario: Failure with no cache
+- **WHEN** a live fetch raises and no cache entry exists
+- **THEN** the provider reports status `error` and other providers are unaffected
+
+### Requirement: Append-only history log
+
+On every successful live fetch, the system SHALL append one JSON line per usage window to `~/.local/state/tokenmaxxr/history.jsonl`. Each line MUST contain `ts` (fetch time, UTC ISO 8601), `provider`, `window` (label), and `pct_used`. Cache hits MUST NOT write history. The system MUST NOT require a database for history storage.
+
+#### Scenario: History written on live fetch only
+- **WHEN** a live fetch of a provider with three windows succeeds
+- **THEN** three lines are appended to history.jsonl
+- **AND** a subsequent cache-hit fetch appends nothing
+
+#### Scenario: Failed fetch writes no history
+- **WHEN** a live fetch fails (serving stale or error)
+- **THEN** no lines are appended to history.jsonl for that provider