claude-usage/README.md

claude-usage

A Linux system tray indicator that shows your Claude.ai usage — current session (5-hour) and weekly — directly in the panel.

Renders a small ring icon with the percentage, updates every 10 minutes, and has an optional "live" mode that keeps a Chromium instance open and reads the DOM every 15 seconds.

How it works

Claude.ai does not expose a public usage API, so this scrapes https://claude.ai/settings/usage using a logged-in Playwright session:

• scraper.ts — Playwright + Chromium. On Linux, it uses Xvfb (a virtual display) to run the browser "headed" (required to pass Cloudflare) without showing any windows. The session is persisted to session/state.json so you only need to log in once.
• tray.py — GTK3 + AyatanaAppIndicator3. Draws the icon with Cairo, calls the scraper via bun, and renders the result as a circular progress ring (green / yellow / red by percent).

Platform support

Component	Linux	macOS	Windows
scraper.ts (CLI)	Full	Works without Xvfb (browser visible)	Works without Xvfb (browser visible)
tray.py (system tray)	Full	Not supported	Not supported

The tray indicator depends on GTK3 + AyatanaAppIndicator3, which is Linux-only. Porting it to Windows or macOS would require swapping in something like pystray (cross-platform tray) or rumps (macOS).

The scraper itself is portable — it's just Bun + Playwright. The only Linux-specific part is the Xvfb wrapper used to hide the browser window during automated polling.

---

Linux

Requirements

• bun — installed at ~/.bun/bin/bun (the path is hard-coded in tray.py; edit if yours differs)
• Python 3 with PyGObject, AyatanaAppIndicator3, cairo
• Xvfb — virtual display server
• Playwright Chromium

On Debian/Ubuntu/Mint:

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

Install

The tray script expects the repo at ~/.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

First login (opens a real Chromium window so you can log in manually):

bun scraper.ts --login

After that, the session is stored in session/state.json.

Run the tray

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

Add it as a startup application in Cinnamon/GNOME so it launches at login.

Tray menu:

• Session / Weekly — current percent + reset time
• Update Now — force an immediate refresh
• Live Mode — switch to 15-second polling (keeps Chromium open in the background)
• Login — re-run the login flow if your session expires
• Quit

CLI usage

bun scraper.ts            # pretty output with colors and progress bars
bun scraper.ts --json     # single JSON line — useful for scripts
bun scraper.ts --live     # JSON Lines, one per 15 seconds (Ctrl+C to stop)
bun scraper.ts --login    # open browser for a fresh login

---

Windows

The tray (tray.py) won't run on Windows. The scraper does, with two changes.

Requirements

• Bun for Windows (or Node.js — bun is just used as a TypeScript runner)
• Playwright Chromium: bunx playwright install chromium

Patch the scraper

Two pieces in scraper.ts reference Linux-only Xvfb. On Windows, replace each check() and live() Xvfb spawn block with a plain Chromium launch (drop the Xvfb spawn and the env: { ..., DISPLAY: display } part). The browser window will be visible while it's running — that's the trade-off without Xvfb. If you want it hidden, run Chromium with headless: true and accept that Cloudflare may block you intermittently.

A simpler alternative: only ever invoke --login and --json (one-shot calls), and accept that a browser window flashes up briefly each time.

Run

bun scraper.ts --login        # log in once
bun scraper.ts --json         # poll usage

To poll on a schedule, set up a Task Scheduler job that runs the --json command and pipes the output somewhere useful (a log file, a notification, a Streamdeck button — your choice).

A proper Windows tray port would mean rewriting tray.py against pystray + Pillow, which isn't done here.

---

macOS

Same story as Windows: the scraper works (no Xvfb needed — just remove the Xvfb spawn), the tray does not. Use rumps if you want a macOS menubar version.

---

Output format

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

If the session has expired: {"loggedIn": false} and exit code 1.

Files

~/.local/share/claude-usage/
├── scraper.ts          # Playwright scraper
├── tray.py             # GTK tray indicator (Linux)
└── session/
    └── state.json      # Playwright storage state (cookies) — gitignored

The tray writes logs to /tmp/claude-usage-tray.log and generated icons to /tmp/claude-usage-icons/.

Security

session/state.json contains your Claude.ai cookies and is equivalent to your login — do not share it. It is excluded via .gitignore.

The tray enforces a single instance via a PID file at /tmp/claude-usage-tray.pid; restarting it kills any older instances automatically.

License

No license specified — treat as personal/internal use unless the repo owner adds one.