diff --git a/README.md b/README.md
new file mode 100644
index 0000000..53f100d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# 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:
+
+```bash
+sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1 python3-cairo xvfb
+```
+
+## Installasjon
+
+Repo-et forventer å ligge i `~/.local/share/claude-usage/`:
+
+```bash
+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):
+
+```bash
+bun scraper.ts --login
+```
+
+Etterpå ligger sesjonen lagret i `session/state.json`.
+
+## Bruk
+
+### Tray (vanlig modus)
+
+```bash
+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
+
+```bash
+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:
+
+```json
+{
+  "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.