docs — translate README to English, add Windows/macOS guidance
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
133
README.md
133
README.md
@@ -1,32 +1,47 @@
|
|||||||
# claude-usage
|
# 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.
|
A Linux system tray indicator that shows your Claude.ai usage — current session (5-hour) and weekly — directly in the panel.
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
## Hvordan det funker
|
## How it works
|
||||||
|
|
||||||
Claude.ai eksponerer ikke et offentlig usage-API, så denne tråkler `https://claude.ai/settings/usage` med en innlogget Playwright-økt:
|
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. 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.
|
- **`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. Tegner ikonet med Cairo, kaller scraperen via `bun`, og rendrer resultatet som en sirkulær progress-ring (grønn / gul / rød etter prosent).
|
- **`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).
|
||||||
|
|
||||||
## Krav
|
## Platform support
|
||||||
|
|
||||||
- **bun** — `~/.bun/bin/bun` (sti er hardkodet i `tray.py`)
|
| Component | Linux | macOS | Windows |
|
||||||
- **Python 3** med `PyGObject`, `AyatanaAppIndicator3`, `cairo`
|
|-----------|-------|-------|---------|
|
||||||
- **Xvfb** — `sudo apt install xvfb`
|
| `scraper.ts` (CLI) | ✅ Full | ⚠️ Works without Xvfb (browser visible) | ⚠️ Works without Xvfb (browser visible) |
|
||||||
- **Playwright Chromium** — `bunx playwright install chromium`
|
| `tray.py` (system tray) | ✅ Full | ❌ Not supported | ❌ Not supported |
|
||||||
|
|
||||||
På Debian/Ubuntu/Mint:
|
The tray indicator depends on GTK3 + AyatanaAppIndicator3, which is Linux-only. Porting it to Windows or macOS would require swapping in something like [`pystray`](https://github.com/moses-palmer/pystray) (cross-platform tray) or [`rumps`](https://github.com/jaredks/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:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1 python3-cairo xvfb
|
sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1 python3-cairo xvfb
|
||||||
```
|
```
|
||||||
|
|
||||||
## Installasjon
|
### Install
|
||||||
|
|
||||||
Repo-et forventer å ligge i `~/.local/share/claude-usage/`:
|
The tray script expects the repo at `~/.local/share/claude-usage/`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://gt.zyon.no/Stian/claude-usage.git ~/.local/share/claude-usage
|
git clone https://gt.zyon.no/Stian/claude-usage.git ~/.local/share/claude-usage
|
||||||
@@ -35,41 +50,75 @@ bun install playwright
|
|||||||
bunx playwright install chromium
|
bunx playwright install chromium
|
||||||
```
|
```
|
||||||
|
|
||||||
Første innlogging (åpner ekte Chromium så du kan logge inn manuelt):
|
First login (opens a real Chromium window so you can log in manually):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun scraper.ts --login
|
bun scraper.ts --login
|
||||||
```
|
```
|
||||||
|
|
||||||
Etterpå ligger sesjonen lagret i `session/state.json`.
|
After that, the session is stored in `session/state.json`.
|
||||||
|
|
||||||
## Bruk
|
### Run the tray
|
||||||
|
|
||||||
### Tray (vanlig modus)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python3 ~/.local/share/claude-usage/tray.py &
|
python3 ~/.local/share/claude-usage/tray.py &
|
||||||
```
|
```
|
||||||
|
|
||||||
Legg til som autostart i Cinnamon/GNOME for å få den opp ved innlogging.
|
Add it as a startup application in Cinnamon/GNOME so it launches at login.
|
||||||
|
|
||||||
Tray-meny:
|
Tray menu:
|
||||||
- **Session / Weekly** — gjeldende prosent + reset-tidspunkt
|
- **Session / Weekly** — current percent + reset time
|
||||||
- **Update Now** — tving en ny sjekk
|
- **Update Now** — force an immediate refresh
|
||||||
- **Live Mode** — bytt til 15-sekunders oppdatering (holder Chromium åpen)
|
- **Live Mode** — switch to 15-second polling (keeps Chromium open in the background)
|
||||||
- **Login** — kjør innlogging på nytt hvis sesjonen utløper
|
- **Login** — re-run the login flow if your session expires
|
||||||
- **Quit**
|
- **Quit**
|
||||||
|
|
||||||
### CLI
|
### CLI usage
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun scraper.ts # pen utskrift med farger og progress-bar
|
bun scraper.ts # pretty output with colors and progress bars
|
||||||
bun scraper.ts --json # én linje JSON, til skripting
|
bun scraper.ts --json # single JSON line — useful for scripts
|
||||||
bun scraper.ts --live # JSON Lines, én per 15. sekund (Ctrl+C for å stoppe)
|
bun scraper.ts --live # JSON Lines, one per 15 seconds (Ctrl+C to stop)
|
||||||
bun scraper.ts --login # åpne nettleser for ny innlogging
|
bun scraper.ts --login # open browser for a fresh login
|
||||||
```
|
```
|
||||||
|
|
||||||
JSON-format:
|
---
|
||||||
|
|
||||||
|
## Windows
|
||||||
|
|
||||||
|
The tray (`tray.py`) won't run on Windows. The scraper does, with two changes.
|
||||||
|
|
||||||
|
### Requirements
|
||||||
|
|
||||||
|
- [Bun for Windows](https://bun.sh/docs/installation) (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
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -83,22 +132,26 @@ JSON-format:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Hvis sesjonen er utløpt: `{"loggedIn": false}` og exit-kode 1.
|
If the session has expired: `{"loggedIn": false}` and exit code 1.
|
||||||
|
|
||||||
## Filer
|
## Files
|
||||||
|
|
||||||
```
|
```
|
||||||
~/.local/share/claude-usage/
|
~/.local/share/claude-usage/
|
||||||
├── scraper.ts # Playwright-scraper
|
├── scraper.ts # Playwright scraper
|
||||||
├── tray.py # GTK tray-indikator
|
├── tray.py # GTK tray indicator (Linux)
|
||||||
└── session/
|
└── session/
|
||||||
└── state.json # Playwright storage state (cookies) — IKKE i git
|
└── state.json # Playwright storage state (cookies) — gitignored
|
||||||
```
|
```
|
||||||
|
|
||||||
Logger fra tray skrives til `/tmp/claude-usage-tray.log`. Genererte ikoner ligger i `/tmp/claude-usage-icons/`.
|
The tray writes logs to `/tmp/claude-usage-tray.log` and generated icons to `/tmp/claude-usage-icons/`.
|
||||||
|
|
||||||
## Sikkerhet
|
## Security
|
||||||
|
|
||||||
`session/state.json` inneholder Claude.ai-cookies og er ekvivalent med innloggingen din — ikke del den. Den er ekskludert via `.gitignore`.
|
`session/state.json` contains your Claude.ai cookies and is equivalent to your login — do not share it. It is excluded 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.
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user