Files
TokenWatch/LIESMICH.md
T
Jannik 665f12a369
Build and Push Docker Image / build-and-push (push) Canceled after 0s
chore(license): standardize on CC0-1.0 and third-party notices
2026-11-18 01:18:15 +01:00

15 KiB

TokenWatch Logo

TokenWatch

Selbstgehosteter API-Quota- & Limit-Tracker mit Live-Dashboard, 7-Tage-Verlaufsdiagramm und ntfy-Benachrichtigungen.

🇬🇧 English · 🇩🇪 Deutsch


Überblick

TokenWatch ist eine selbstgehostete Webanwendung zur zentralen Überwachung von KI-API-Kontingenten und Rate-Limit-Fenstern über mehrere Anbieter hinweg. Die Anwendung fragt externe Provider-APIs ab, empfängt Webhook-Updates eines lokalen Antigravity-Language-Server-Sync-Skripts, speichert Verlaufsdaten in PostgreSQL, stellt interaktive 7-Tage-Verläufe grafisch dar und verschickt automatische Push-Warnungen über ntfy, sobald konfigurierte Schwellenwerte überschritten werden.

Architektur

+-----------------------------------+        POST /api/webhook/antigravity
| Windows-Host (Antigravity IDE)    | -------------------------------------+
| Push-AntigravityQuota.ps1         |                                      |
|   -> tokenwatch-sync.js           |                                      v
+-----------------------------------+                       +------------------------------+
                                                            | TokenWatch-Server (Express)  |
+-----------------------------------+   REST-API (30-Min-   | Port 3000                    |
| Externe APIs                      |   Cron + Live-Abruf)  | - Statische UI (public/)     |
| - POE (current_balance)           | <-------------------> | - /api/quotas                |
| - MiniMax (coding_plan/remains)   |                       | - /api/history               |
+-----------------------------------+                       +--------------+---------------+
                                                                           |
                                              +----------------------------+----------------------------+
                                              v                                                         v
                               +------------------------------+                          +------------------------------+
                               | PostgreSQL-Datenbank         |                          | ntfy-Server                  |
                               | - quotas (Verlauf)           |                          | Schwellenwert-Warnungen      |
                               | - antigravity_latest (JSONB) |                          +------------------------------+
                               +------------------------------+

Funktionen

  • Multi-Provider-Quota-Tracking:
    • POE: Überwacht den aktuellen Punktestand im Verhältnis zum Limit von 2.500.000, täglichem Refresh (75.000), verfallenden Punkten, Tagen bis zum Cap, dem heutigen Tagesverbrauch (berechnet gegen den ersten UTC-Snapshot des Tages) sowie einem Live-Countdown bis 00:00 Uhr UTC.
    • MiniMax: Überwacht MiniMax (5h) und MiniMax (Weekly) in Prozent (model_name === 'general') inklusive Live-Reset-Countdowns.
    • Antigravity (AG): Überwacht 5 separate Kontingente per Webhook-Push (AG Gemini (5h), AG Gemini (Weekly), AG Claude (5h), AG Claude (Weekly), AG Gemini 4 Argon (Weekly)) inklusive individueller Reset-Zeitstempel (Heute, Morgen oder Wochentag + Countdown).
  • Persistenter Antigravity-Status: Eingehende Webhook-Daten werden in der PostgreSQL-Tabelle antigravity_latest (JSONB) gespeichert und beim Serverstart automatisch wiederhergestellt.
  • Automatisierte Cron-Snapshots & ntfy-Alerts: Alle 30 Minuten (*/30 * * * *) ruft node-cron alle Quotas ab, speichert sie in PostgreSQL und sendet bei Überschreitung von ALERT_THRESHOLD_PERCENT (Standard: 80) eine ntfy-Meldung (Title: TokenWatch Alert, Tags: warning,robot).
  • 7-Tage-Verlaufsdiagramm: Interaktives Chart.js-Liniendiagramm, das Datenpunkte in 5-Minuten-Intervallen für AG Gemini (5h), AG Claude (5h), POE und MiniMax (5h) gruppiert.
  • 6 wählbare Fortschrittsbalken-Themes: Live-Wechsel zwischen Standard, Pac-Man, Battery, Nyan Cat, Matrix und Lava (passt auch die Chart.js-Farben dynamisch an).
  • Konfetti-Effekt bei 100 %: Löst bei Erreichen von 100 % eine canvas-confetti-Animation aus und zeigt bei Nicht-POE-Providern LIMIT REACHED! an.
  • Lokale Antigravity-Sync- & Debug-Werkzeuge: Enthält tokenwatch-sync.js, Push-AntigravityQuota.ps1 (für die Windows-Aufgabenplanung) sowie das plattformübergreifende Debug-Skript fetch-quota.js zum Auslesen der Rohantwort des lokalen Language Servers.

Funktionsweise & Tech-Stack

Interner Ablauf

  1. Serverstart (src/server.ts): Startet Express auf 0.0.0.0:3000, liefert statische Dateien aus public/ aus, initialisiert die PostgreSQL-Tabellen (quotas und antigravity_latest) über initDb() und lädt gespeicherte Antigravity-Werte über initAntigravityFromDb().
  2. Quota-Abruf (src/services/providers.ts):
    • fetchPoeQuota() fragt https://api.poe.com/usage/current_balance ab.
    • fetchMinimaxQuota() fragt https://api.minimax.io/v1/api/openplatform/coding_plan/remains ab.
    • fetchAntigravityQuota() liest den In-Memory-antigravityCache, der über POST /api/webhook/antigravity aktualisiert oder beim Start aus PostgreSQL geladen wird.
  3. Alert-Logik (src/cron.ts & src/services/ntfy.ts):
    • Bei POE (hier steht percentage für das verbleibende Kontingent) wird gewarnt, wenn percentage <= (100 - ALERT_THRESHOLD_PERCENT) (Standard: <= 20 % verbleibend).
    • Bei MiniMax und Antigravity (hier steht percentage für das verbrauchte Kontingent) wird gewarnt, wenn percentage >= ALERT_THRESHOLD_PERCENT (Standard: >= 80 % verbraucht).
  4. Lokaler Antigravity-Sync (tokenwatch-sync.js): Sucht laufende language_server*-Prozesse über PowerShell (Get-CimInstance Win32_Process), liest --csrf_token und --extension_server_port aus, ermittelt offene Loopback-Ports (Get-NetTCPConnection mit netstat -ano als Fallback), ruft POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary auf und sendet die extrahierten Werte an /api/webhook/antigravity.

Tech-Stack & Ports

Komponente Technologie / Version Details
Laufzeitumgebung Node.js 24 (node:24-alpine) CommonJS-TypeScript-Build (tsc -> dist/)
Backend Express ^5.2.1, TypeScript ^7.0.2 REST-API + Auslieferung statischer Dateien
Scheduler node-cron ^4.6.0 Läuft alle 30 Minuten (*/30 * * * *)
HTTP-Client axios ^1.20.0 Provider-API-Abfragen & ntfy-Alerts
Datenbank PostgreSQL (postgres:15-alpine, pg ^8.23.0) Tabellen: quotas, antigravity_latest
Frontend Natives HTML/CSS/JS, Chart.js, canvas-confetti Ausgeliefert aus public/
Standard-Port 3000 (Container) / 3500 (Jannik-Cloud-Host-Bind) Konfigurierbar über PORT

Voraussetzungen & Installation

Voraussetzungen

  • Lokale Entwicklung: Node.js (v20+ / v24 empfohlen), npm und eine laufende PostgreSQL-Instanz.
  • Docker-Deployment: Docker und Docker Compose.
  • Antigravity-Sync (optional): Windows-Rechner mit laufender Antigravity IDE, Node.js und PowerShell.

Lokale Installation

  1. Repository klonen:

    git clone https://git.orfel.de/Jannik/TokenWatch.git
    cd TokenWatch
    
  2. Abhängigkeiten installieren:

    npm install
    
  3. Umgebungsdatei aus .env.example erstellen:

    cp .env.example .env
    

    Danach PostgreSQL-Zugangsdaten, NTFY_URL und API-Keys in .env eintragen.

  4. Im Entwicklungsmodus (tsx) starten oder für Produktion bauen:

    # Entwicklung
    npm run dev
    
    # Produktions-Build & Start
    npm run build
    npm start
    

Docker-Compose-Setup

TokenWatch gemeinsam mit PostgreSQL (postgres:15-alpine) starten:

cp .env.example .env
# .env mit Zugangsdaten und API-Keys ausfüllen
docker compose up -d

Das Dashboard ist anschließend unter http://localhost:3000 erreichbar.

Jannik-Cloud-Produktivdeployment

Eine fertige Deployment-Vorlage liegt in deployment-template/:

  1. Den Inhalt von deployment-template/ in das Verzeichnis services/tokenwatch/ im Jannik-Cloud-Repository kopieren.
  2. In services/tokenwatch/ das Skript bash generate-env.sh ausführen, um zufällige PostgreSQL-Zugangsdaten zu generieren und optional .env nach .env.age zu verschlüsseln (über keys/age-public-key.txt).
  3. Bei Bedarf Provider-API-Keys (POE_API_KEY, MINIMAX_API_KEY usw.) ergänzen.
  4. tokenwatch.caddy konfiguriert den Reverse-Proxy für tw.orfel.de, token.orfel.de und tokenwatch.orfel.de auf tokenwatch:3000; docker-compose.yml bindet 127.0.0.1:3500:3000 im externen Netzwerk jannik-cloud-net.
  5. Hinweis: .github/workflows/docker.yml enthält zudem einen GitHub-Actions-Workflow, der bei Pushes auf main oder master ein Image nach ghcr.io/<owner>/<repo>:latest baut und pusht.

Konfiguration

Umgebungsvariablen (.env.example)

Variable Beschreibung Standard / Beispiel
PORT HTTP-Server-Port 3000
DB_USER PostgreSQL-Benutzername postgres
DB_HOST PostgreSQL-Hostname postgres
DB_NAME Name der PostgreSQL-Datenbank tokenwatch
DB_PASSWORD PostgreSQL-Passwort your_db_password
DB_PORT PostgreSQL-Port 5432
NTFY_URL ntfy-Topic-URL für Schwellenwert-Alerts https://ntfy.orfel.de/Token-Watch (Fallback in ntfy.ts: https://ntfy.orfel.de/tokenwatch_dummy)
ALERT_THRESHOLD_PERCENT Schwellenwert in Prozent (>= verbraucht bzw. <= 100 - N verbleibend bei POE) 80
POE_API_KEY Bearer-Token für api.poe.com/usage/current_balance —
MINIMAX_API_KEY Bearer-Token für api.minimax.io/v1/api/openplatform/coding_plan/remains —
ANTIGRAVITY_API_KEY Optionaler Platzhalter in .env.example / Compose —
ANTIGRAVITY_ENDPOINT Optionaler Platzhalter in .env.example / Compose https://api.antigravity.google/v1/quota

Docker-Volumes

  • pgdata:/var/lib/postgresql/data — Persistiert in docker-compose.yml den Verlauf in quotas sowie den Zustand in antigravity_latest.

Nutzung

Web-Dashboard

Öffne http://localhost:3000 (bzw. deine konfigurierte Domain), um:

  • Aktuelle Fortschrittsbalken, Reset-Zeiten (Heute/Morgen/Wochentag) und Countdowns für POE, Antigravity und MiniMax anzuzeigen.
  • Über das Dropdown Progress Bar Style zwischen 6 Designs zu wechseln:
    1. Standard
    2. Pac-Man
    3. Battery
    4. Nyan Cat
    5. Matrix
    6. Lava
  • Den 7-Tage-Verlauf im Chart.js-Bereich History zu verfolgen.

API-Endpunkte

Methode Endpunkt Beschreibung
GET /api/quotas Liefert die aktuellen Quota-Objekte aller Provider inklusive meta.todayUsed für POE.
GET /api/history Liefert die letzten 7 Tage aus der PostgreSQL-Tabelle quotas in chronologischer Reihenfolge.
POST /api/webhook/antigravity Aktualisiert die 5 Antigravity-Einträge im Speicher und persistiert sie in antigravity_latest.

Beispiel-Payload für POST /api/webhook/antigravity:

{
  "gemini_5h_remaining": 85,
  "gemini_weekly_remaining": 90,
  "claude_5h_remaining": 100,
  "claude_weekly_remaining": 75,
  "gemini_argon_weekly_remaining": 100,
  "gemini_5h_reset": "2026-01-01T15:00:00Z",
  "gemini_weekly_reset": "2026-01-07T00:00:00Z",
  "claude_5h_reset": null,
  "claude_weekly_reset": null,
  "gemini_argon_weekly_reset": null
}

Lokaler Antigravity-Sync (Windows)

  1. Stelle sicher, dass url in tokenwatch-sync.js auf deine TokenWatch-Instanz zeigt (Standard: https://tokenwatch.orfel.de/api/webhook/antigravity).
  2. Manuell ausführen:
    .\Push-AntigravityQuota.ps1
    
    Oder direkt per Node:
    node tokenwatch-sync.js
    
  3. Automatisierung über Windows-Aufgabenplanung:
    • Trigger: Alle 30 Minuten
    • Aktion: Programm starten
    • Programm: powershell
    • Argumente: -ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"
  4. Rohdaten des Language Servers debuggen:
    node fetch-quota.js
    
    Fragt /exa.language_server_pb.LanguageServerService/GetUserStatus beim lokalen Language Server ab (unterstützt Windows, macOS und Linux) und gibt die vollständige JSON-Antwort aus.

Projektstruktur

TokenWatch/
├── .github/
│   └── workflows/
│       └── docker.yml              # GitHub-Actions-Workflow zum Bauen/Pushen nach ghcr.io
├── deployment-template/
│   ├── README.md                   # Deployment-Anleitung für Jannik-Cloud
│   ├── docker-compose.yml          # Produktives Compose mit jannik-cloud-net
│   ├── generate-env.sh             # Erzeugt DB-Passwörter & optional .env.age
│   ├── service.enabled             # Aktivierungsdatei für Jannik-Cloud
│   └── tokenwatch.caddy            # Caddy-Reverse-Proxy-Konfiguration
├── public/
│   ├── logos/                      # Provider-.ico-Dateien
│   ├── app.js                      # Frontend-Logik, Countdowns, Chart.js & Themes
│   ├── favicon.png                 # TokenWatch-Logo & Favicon
│   ├── index.html                  # Dashboard-HTML
│   ├── logo-*.png / .ico / .svg    # Provider-Icons (POE, Gemini, Claude, MiniMax, AG)
│   └── style.css                   # Dark-UI & 6 Fortschrittsbalken-Themes
├── src/
│   ├── services/
│   │   ├── db.ts                   # PostgreSQL-Pool, Tabellen-Init, Verlauf & AG-Persistenz
│   │   ├── ntfy.ts                 # ntfy-Benachrichtigungen
│   │   └── providers.ts            # POE-, MiniMax- & Antigravity-Provider-Logik
│   ├── cron.ts                     # 30-Minuten-Cron-Job & Schwellenwert-Prüfung
│   └── server.ts                   # Express-App & REST-API-Endpunkte
├── .env.example                    # Beispiel-Umgebungsvariablen
├── Dockerfile                      # Node-24-Alpine-Container mit TypeScript-Build
├── docker-compose.yml              # Lokales/Standalone-Compose mit PostgreSQL 15
├── fetch-quota.js                  # Plattformübergreifendes Debug-Skript für Language Server
├── language-server-process-utils.js# Prozesssuche & CLI-Argument-Extraktion
├── package.json                    # Abhängigkeiten und npm-Skripte
├── Push-AntigravityQuota.ps1       # PowerShell-Wrapper für Windows-Aufgabenplanung
├── tokenwatch-sync.js              # Lokaler Antigravity-Language-Server -> Webhook-Sync
└── tsconfig.json                   # TypeScript-Konfiguration

Lizenz

Der eigene Quellcode und die Konfiguration dieses Projekts stehen unter CC0 1.0 Universal (Public Domain) — Details in LICENSE.

Externe Abhängigkeiten, die über Paketmanager oder Docker-Images installiert werden, behalten ihre jeweiligen eigenen Open-Source-Lizenzen.