claude-live-dashboard/BENUTZERHANDBUCH.md

# Claude Live Dashboard — Benutzerhandbuch

Dieses Handbuch richtet sich an Anwender, die Claude Live Dashboard installieren
und nutzen möchten. Wer die Anwendung selbst bauen oder am Quellcode arbeiten
möchte, findet die technische Dokumentation in der `README.md`.

## Was die Anwendung tut

Claude Live Dashboard ist ein kleines, immer sichtbares Fenster, das anzeigt,
wie stark Ihr Claude-Abo gerade ausgelastet ist: das laufende 5-Stunden-Fenster,
das Wochenkontingent, der Zeitpunkt der nächsten Zurücksetzung und — sofern Ihr
Abo es ausweist — das verbleibende Nutzungsguthaben.

Die Anzeige liest dafür ausschließlich die Protokolldateien, die Claude Code
auf Ihrem Rechner ohnehin selbst anlegt. Es wird nichts zusätzlich
mitgeschnitten. Optional (und standardmäßig aktiv) fragt die Anwendung
zusätzlich denselben Server-Endpunkt ab, den auch der Befehl `/usage` in
Claude Code nutzt, um exakte statt geschätzter Werte anzuzeigen — dazu weiter
unten mehr unter „Datenschutz und Sicherheit“.

## Voraussetzungen

- Windows 10/11 oder Ubuntu (bzw. eine vergleichbare Linux-Distribution)
- Claude Code muss installiert sein und mindestens einmal benutzt worden sein
  — ohne vorhandene Protokolldateien hat das Dashboard nichts anzuzeigen

## Installation

### Windows

Zwei Varianten stehen zur Wahl:

- **Installer** (`Claude Live Dashboard-<Version>-x64.exe`): Doppelklick
  starten, Installationsordner bestätigen oder ändern, fertig. Es werden eine
  Desktop- und eine Startmenü-Verknüpfung angelegt. Administratorrechte sind
  **nicht** nötig, die Installation erfolgt in Ihr Benutzerprofil.
- **Portable** (`Claude Live Dashboard-<Version>-portable.exe`): läuft ohne
  Installation direkt von jedem Ort, z. B. einem USB-Stick.

Da die Anwendung nicht mit einem kostenpflichtigen Code-Signing-Zertifikat
signiert ist, zeigt Windows beim allerersten Start eine SmartScreen-Warnung
(„Der Computer wurde durch Windows geschützt“). Über **Weitere Informationen**
und dann **Trotzdem ausführen** lässt sie sich bestätigen. Das ist normal für
Software ohne kommerzielles Zertifikat und kein Hinweis auf ein Problem.

### Linux (Ubuntu und verwandte Distributionen)

- **`.deb`-Paket**: `sudo apt install ./Claude-Live-Dashboard-<Version>-amd64.deb`
  — richtet Menüeintrag und Symbol automatisch ein.
- **AppImage**: Datei ausführbar machen (`chmod +x Claude-Live-Dashboard-<Version>-x64.AppImage`)
  und starten. Setzt `libfuse2` voraus; unter Ubuntu 24.04 ist das ggf.
  nachzuinstallieren (`sudo apt install libfuse2t64` oder `libfuse2`, je nach
  Version).

Unter GNOME braucht das Tray-Symbol die Erweiterung **AppIndicator** — bei
Standard-Ubuntu ist sie bereits vorinstalliert. Fehlt sie, läuft die Anwendung
trotzdem, nur ohne sichtbares Symbol in der oberen Leiste.

## Erster Start

Nach dem Start erscheint das Fenster rechts oben auf dem Bildschirm und bleibt
über allen anderen Fenstern sichtbar. Zusätzlich landet ein Symbol im
Infobereich der Taskleiste (Windows) bzw. in der oberen Systemleiste (Linux).

Unter Windows liegt das Symbol zunächst häufig im Überlaufbereich hinter dem
Pfeil `^` — per Drag & Drop lässt es sich dauerhaft sichtbar an die Taskleiste
heften.

## Die Oberfläche

**Kopfzeile** — per Ziehen lässt sich das Fenster frei positionieren, die
Position wird gemerkt.

| Element | Bedeutung |
|---|---|
| Statuspunkt | Zeigt den Zustand der Datenquellen, siehe unten |
| Pfeil-Symbol (nur bei neuem Release) | Öffnet die Release-Seite im Browser |
| Zahnrad | Öffnet die Einstellungen |
| `ⓘ` | Öffnet ein Menü mit Benutzerhandbuch, Disclaimer und Lizenz — Klick auf einen Eintrag zeigt den Text in einem eigenen Fenster |
| `–` | Blendet das Fenster aus (Rückkehr über das Tray-Symbol) |

**Anzeigebereich**

- **Laufende Sitzung** — Auslastung des aktuellen 5-Stunden-Fensters, dazu
  verbrauchte Tokens und Verbrauchstempo.
- **Wochenkontingent** — das übergeordnete Limit über alle Modelle, mit dem
  Zeitpunkt der nächsten Zurücksetzung.
- **Nutzungsguthaben** — erscheint nur, wenn Ihr Abo ein zusätzliches
  Geldbudget führt.
- Ein Satz darunter sagt, wie lange das Wochenkontingent bei aktuellem Tempo
  noch reicht — gerechnet in tatsächlicher Arbeitszeit, nicht in Kalendertagen.

**„Details“** klappt eine erweiterte Ansicht auf: Verbrauch je Modell, Tempo,
und wie verlässlich die angezeigten Prozentwerte sind.

### Endpunkt-Status und Fehler-/Ereignis-Log

Der Punkt links vom Zahnrad zeigt auf einen Blick, ob alles rund läuft:

| Aussehen | Bedeutung |
|---|---|
| Grüner Punkt | Alles in Ordnung |
| Gelbe Raute | Die optionale Serverabfrage ist gerade gestört — die Anzeige rechnet währenddessen lokal weiter, ist also weiterhin nutzbar, nur mit geschätzten statt exakten Werten |
| Rote Raute | Die lokalen Protokolldateien sind nicht lesbar — das ist die eigentliche Datengrundlage, hier lohnt ein Blick ins Log |

Ein Klick auf den Punkt öffnet ein eigenes Fenster mit einer Liste aller
bisherigen Störungen samt Zeitpunkt, sowie App-Ereignissen wie „App
installiert“ oder „Auf Version … aktualisiert“. Diese Liste bleibt auch über
einen Neustart hinweg erhalten und lässt sich über den Knopf **Log löschen**
jederzeit zurücksetzen. Bei einer Fehlermeldung im Programm ist ein Blick in
dieses Log meist der schnellste Weg herauszufinden, was los ist.

## Einstellungen

Das Zahnrad öffnet den Einstellungsdialog:

- **Deckkraft** — wie durchscheinend das Fenster ist.
- **Klicks durchlassen** — macht das Fenster für die Maus „unsichtbar“, es
  liegt dann über der Arbeit, ohne sie zu stören. Zurückschalten geht über das
  Tray-Menü (siehe unten), da das Fenster in diesem Zustand selbst nicht mehr
  anklickbar ist.
- **Mit Windows/dem System starten** — startet die Anwendung automatisch bei
  der Anmeldung.
- **Serverabfrage** — kann abgeschaltet werden, falls die Anzeige rein lokal
  arbeiten soll (dann sind alle Werte Näherungen statt exakter Zahlen).
- **Nach Updates suchen** — prüft rund eine Minute nach dem Start einmalig,
  ob auf dem Projekt-Server eine neuere Version vorliegt. Falls ja,
  erscheint eine Systembenachrichtigung, und ein Pfeil-Symbol im
  Titelbalken bleibt sichtbar, bis aktualisiert wird. Klick auf
  Benachrichtigung oder Symbol öffnet die Release-Seite im Browser. Diese
  Einstellung wirkt erst beim nächsten Start.
- **Bezugsgrößen, Gewichtung, Wochenfenster** — fortgeschrittene Feineinstellungen
  für den Fall, dass die Serverabfrage dauerhaft nicht zur Verfügung steht;
  im Normalbetrieb müssen Sie hier nichts anpassen.

Änderungen wirken sofort, ein Neustart ist nicht nötig (Ausnahme: „Nach
Updates suchen", siehe oben). `Strg`+`S` speichert, `Esc` schließt den
Dialog ohne zu speichern.

## Tray-Menü

Ein Rechtsklick (Linux) bzw. Klick (Windows) auf das Symbol im
Infobereich/der Systemleiste öffnet ein Menü mit: Dashboard anzeigen/ausblenden,
Deckkraft, Klick-Durchlässigkeit, Autostart, Einstellungen, Datenordner öffnen
und Beenden.

## Datenschutz und Sicherheit

- Die Anwendung liest ausschließlich Dateien, die Claude Code selbst bereits
  auf Ihrem Rechner ablegt. Es wird nichts zusätzlich protokolliert.
- Standardmäßig fragt sie zusätzlich einen offiziellen Anthropic-Endpunkt ab,
  um exakte statt geschätzter Prozentwerte anzuzeigen. Dafür wird dasselbe
  Zugriffstoken verwendet, das Claude Code selbst benutzt — es wird gelesen,
  aber nie gespeichert, nie protokolliert und ausschließlich an diesen einen,
  offiziellen Host gesendet.
- Diese Serverabfrage lässt sich in den Einstellungen jederzeit abschalten;
  die Anwendung funktioniert dann weiter, nur mit geschätzten statt exakten
  Werten.
- Über den Knopf „Zugriffstoken erneuern" im Endpunkt-Status-Fenster lässt
  sich das Zugriffstoken bei Bedarf manuell erneuern. Dabei wird das
  Refresh-Token aus derselben Anmeldedatei gegen ein neues Zugriffstoken
  eingetauscht und das Ergebnis dorthin zurückgeschrieben — Claude Code
  selbst profitiert automatisch davon. Das geschieht ausschließlich auf
  Klick, nie automatisch im Hintergrund, und auch dabei wird kein Token
  protokolliert.
- Ist „Nach Updates suchen" aktiviert, fragt die Anwendung rund eine Minute
  nach dem Start einmalig den selbst gehosteten Gitea-Server
  (`git.conatum.net`) nach der neuesten Versionsnummer ab — ohne
  Zugriffstoken und ohne weitere Daten. Abschaltbar in den Einstellungen.
- Es findet keine Übertragung an Dritte statt.

## Deinstallation

**Windows:** über *Einstellungen ▸ Apps* bzw. den mitinstallierten
Deinstallierer im Installationsordner. Ihre Konfiguration und die
Kalibrierungsdaten bleiben dabei erhalten, falls Sie die Anwendung später
erneut installieren.

**Linux:** `.deb`-Installation mit `sudo apt remove claude-live-dashboard`;
ein AppImage genügt zu löschen.

## Häufige Fragen

**Das Fenster zeigt keine Zahlen an.** Vermutlich wurde Claude Code auf diesem
Rechner noch nicht benutzt — die Anzeige braucht mindestens einen
protokollierten Verlauf, um etwas darzustellen.

**Der Statuspunkt ist rot.** Die lokalen Protokolldateien konnten nicht
gelesen werden. Ein Klick auf den Punkt zeigt im Log den genauen Grund.

**Der Statuspunkt ist gelb.** Nur die optionale Serverabfrage ist gerade
gestört, meist vorübergehend (z. B. Netzwerkproblem oder ein abgelaufenes
Zugriffstoken). Ein Klick auf „Zugriffstoken erneuern" im
Endpunkt-Status-Fenster erneuert es sofort; andernfalls übernimmt das Claude
Code beim nächsten eigenen Start. Die Anzeige selbst funktioniert
währenddessen weiter.

**Windows warnt beim ersten Start.** Normal bei unsignierter Software, siehe
Abschnitt „Installation“ oben.

**Nach einem Update sehe ich eine Benachrichtigung.** Das ist beabsichtigt:
Die Anwendung erkennt neue Versionen automatisch und weist einmalig darauf
hin. Ihre Einstellungen und Kalibrierung bleiben davon unberührt.

**Ich bekomme eine Benachrichtigung über eine neue Version / ein
Pfeil-Symbol erscheint im Titelbalken.** Das ist eine andere Meldung als
oben: Die Anwendung hat rund eine Minute nach dem Start auf dem
Projekt-Server ein neueres Release gefunden. Ein Klick auf Benachrichtigung
oder Symbol öffnet die Release-Seite im Browser — heruntergeladen oder
installiert wird nichts automatisch. Das Symbol bleibt sichtbar, bis eine
neuere Version installiert wurde. Abschaltbar über die Einstellung „Nach
Updates suchen".