claude-usage/README.md

claude-usage

System tray-indikator for Linux som viser hvor mye av Claude.ai-kvoten din du har brukt — sesjon (5-timers) og ukentlig — direkte i panelet ditt.

Skriver et lite ringikon med prosent, oppdaterer hvert 10. minutt, og har en valgfri "live"-modus som holder en Chromium-instans åpen og leser DOM-en hvert 15. sekund.

Hvordan det funker

Claude.ai eksponerer ikke et offentlig usage-API, så denne tråkler https://claude.ai/settings/usage med en innlogget Playwright-økt:

• scraper.ts — Playwright + Chromium. Bruker Xvfb (virtuelt display) slik at nettleseren kjører "headed" (kreves for å passere Cloudflare) men ikke vises på skjermen. Lagrer sesjonen i session/state.json slik at innlogging kun skjer én gang.
• tray.py — GTK3 + AyatanaAppIndicator3. Tegner ikonet med Cairo, kaller scraperen via bun, og rendrer resultatet som en sirkulær progress-ring (grønn / gul / rød etter prosent).

Krav

• bun — ~/.bun/bin/bun (sti er hardkodet i tray.py)
• Python 3 med PyGObject, AyatanaAppIndicator3, cairo
• Xvfb — sudo apt install xvfb
• Playwright Chromium — bunx playwright install chromium

På Debian/Ubuntu/Mint:

sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1 python3-cairo xvfb

Installasjon

Repo-et forventer å ligge i ~/.local/share/claude-usage/:

git clone https://gt.zyon.no/Stian/claude-usage.git ~/.local/share/claude-usage
cd ~/.local/share/claude-usage
bun install playwright
bunx playwright install chromium

Første innlogging (åpner ekte Chromium så du kan logge inn manuelt):

bun scraper.ts --login

Etterpå ligger sesjonen lagret i session/state.json.

Bruk

Tray (vanlig modus)

python3 ~/.local/share/claude-usage/tray.py &

Legg til som autostart i Cinnamon/GNOME for å få den opp ved innlogging.

Tray-meny:

• Session / Weekly — gjeldende prosent + reset-tidspunkt
• Update Now — tving en ny sjekk
• Live Mode — bytt til 15-sekunders oppdatering (holder Chromium åpen)
• Login — kjør innlogging på nytt hvis sesjonen utløper
• Quit

CLI

bun scraper.ts            # pen utskrift med farger og progress-bar
bun scraper.ts --json     # én linje JSON, til skripting
bun scraper.ts --live     # JSON Lines, én per 15. sekund (Ctrl+C for å stoppe)
bun scraper.ts --login    # åpne nettleser for ny innlogging

JSON-format:

{
  "sessionUsed": 42,
  "sessionResets": "Mon 14:00",
  "weeklyUsed": 18,
  "weeklyResets": "Tue 09:00",
  "sonnetUsed": 12,
  "extraSpent": "0.00",
  "loggedIn": true
}

Hvis sesjonen er utløpt: {"loggedIn": false} og exit-kode 1.

Filer

~/.local/share/claude-usage/
├── scraper.ts          # Playwright-scraper
├── tray.py             # GTK tray-indikator
└── session/
    └── state.json      # Playwright storage state (cookies) — IKKE i git

Logger fra tray skrives til /tmp/claude-usage-tray.log. Genererte ikoner ligger i /tmp/claude-usage-icons/.

Sikkerhet

session/state.json inneholder Claude.ai-cookies og er ekvivalent med innloggingen din — ikke del den. Den er ekskludert via .gitignore.

Tray-en kjører bare én instans om gangen (PID-fil i /tmp/claude-usage-tray.pid); start på nytt dreper eldre prosesser automatisk.